Implement Hopcroft-karp algorithm to find the maximum matching of a undirected bipartite graph

Author: Akshat-Shu

pydatastructs/graphs/__init__.py

@@ -21,7 +21,10 @@
     all_pair_shortest_paths,
     topological_sort,
     topological_sort_parallel,
-    max_flow
+    max_flow,
+    maximum_matching,
+    maximum_matching_parallel,
+    bipartite_coloring
 )
 
 __all__.extend(algorithms.__all__)

pydatastructs/graphs/algorithms.py

@@ -23,7 +23,10 @@
     'all_pair_shortest_paths',
     'topological_sort',
     'topological_sort_parallel',
-    'max_flow'
+    'max_flow',
+    'maximum_matching',
+    'maximum_matching_parallel',
+    'bipartite_coloring'
 ]
 
 Stack = Queue = deque
@@ -1216,3 +1219,322 @@ def max_flow(graph, source, sink, algorithm='edmonds_karp', **kwargs):
         f"Currently {algorithm} algorithm isn't implemented for "
         "performing max flow on graphs.")
     return getattr(algorithms, func)(graph, source, sink)
+
+def bipartite_coloring(graph: Graph, **kwargs) -> tuple[bool, dict]:
+    """
+    Finds a 2-coloring of the given graph if it is bipartite.
+
+    Parameters
+    ==========
+
+    graph: Graph
+        The graph under consideration.
+    invert: bool
+        If True, the colors are inverted.
+    make_undirected: bool
+        If False, the input graph should be undirected else it can be made undirected by setting this to True
+    backend: pydatastructs.Backend
+        The backend to be used.
+        Optional, by default, the best available
+        backend is used.
+
+    Returns
+    =======
+
+    tuple
+        A tuple containing a boolean value and a dictionary.
+        The boolean value is True if the graph is bipartite
+        and False otherwise. The dictionary contains the
+        color assigned to each vertex.
+
+    Examples
+    ========
+
+    >>> from pydatastructs import Graph, AdjacencyListGraphNode, bipartite_coloring
+    >>> v_1 = AdjacencyListGraphNode('v_1')
+    >>> v_2 = AdjacencyListGraphNode('v_2')
+    >>> v_3 = AdjacencyListGraphNode('v_3')
+    >>> v_4 = AdjacencyListGraphNode('v_4')
+    >>> graph = Graph(v_1, v_2, v_3, v_4)
+    >>> graph.add_edge('v_1', 'v_2')
+    >>> graph.add_edge('v_2', 'v_3')
+    >>> graph.add_edge('v_4', 'v_1')
+    >>> bipartite_coloring(graph)
+    >>> (True, {'v_1': 0, 'v_2': 1, 'v_4': 1, 'v_3': 0})
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Bipartite_graph
+    """
+
+    color = {}
+    queue = Queue()
+    invert = kwargs.get('invert', False)
+    make_unidirected = kwargs.get('make_undirected', False)
+
+    if make_unidirected:
+        graph = graph.to_undirected_adjacency_list()
+
+    for start in graph.vertices:
+        if start not in color:
+            queue.append(start)
+            color[start] = 1 if invert else 0
+
+            while queue:
+                u = queue.popleft()
+                for v in graph.neighbors(u):
+                    v_name = v.name
+                    if v_name not in color:
+                        color[v_name] = 1 - color[u]
+                        queue.append(v_name)
+                    elif color[v_name] == color[u]:
+                        return (False, {})
+
+    return (True, color)
+
+
+def _maximum_matching_hopcroft_karp_(graph: Graph):
+    U = set()
+    V = set()
+    bipartiteness, coloring = bipartite_coloring(graph)
+
+    if not bipartiteness:
+        raise ValueError("Graph is not bipartite.")
+
+    for node, c in coloring.items():
+        if c == 0:
+            U.add(node)
+        else:
+            V.add(node)
+
+
+    pair_U = {u: None for u in U}
+    pair_V = {v: None for v in V}
+    dist = {}
+
+    def bfs():
+        queue = Queue()
+        for u in U:
+            if pair_U[u] is None:
+                dist[u] = 0
+                queue.append(u)
+            else:
+                dist[u] = float('inf')
+        dist[None] = float('inf')
+        while queue:
+            u = queue.popleft()
+            if dist[u] < dist[None]:
+                for v in graph.neighbors(u):
+                    if dist[pair_V[v.name]] == float('inf'):
+                        dist[pair_V[v.name]] = dist[u] + 1
+                        queue.append(pair_V[v.name])
+        return dist[None] != float('inf')
+
+    def dfs(u):
+        if u is not None:
+            for v in graph.neighbors(u):
+                if dist[pair_V[v.name]] == dist[u] + 1:
+                    if dfs(pair_V[v.name]):
+                        pair_V[v.name] = u
+                        pair_U[u] = v.name
+                        return True
+            dist[u] = float('inf')
+            return False
+        return True
+
+    matching = set()
+    while bfs():
+        for u in U:
+            if pair_U[u] is None:
+                if dfs(u):
+                    matching.add((u, pair_U[u]))
+
+    return matching
+
+def maximum_matching(graph: Graph, algorithm: str, **kwargs) -> set:
+    """
+    Finds the maximum matching in the given undirected using the given algorithm.
+
+    Parameters
+    ==========
+
+    graph: Graph
+        The graph under consideration.
+    algorithm: str
+        The algorithm to be used.
+        Currently, following are supported,
+
+        'hopcroft_karp' -> Hopcroft-Karp algorithm for Bipartite Graphs as given in [1].
+    make_undirected: bool
+        If False, the graph should be undirected or unwanted results may be obtained. The graph can be made undirected by setting this to true.
+    backend: pydatastructs.Backend
+        The backend to be used.
+        Optional, by default, the best available
+        backend is used.
+
+    Returns
+    =======
+
+    set
+        The set of edges which form the maximum matching.
+
+    Examples
+    ========
+
+    >>> from pydatastructs import Graph, AdjacencyListGraphNode, maximum_matching
+    >>> v_1 = AdjacencyListGraphNode('v_1')
+    >>> v_2 = AdjacencyListGraphNode('v_2')
+    >>> v_3 = AdjacencyListGraphNode('v_3')
+    >>> v_4 = AdjacencyListGraphNode('v_4')
+    >>> graph = Graph(v_1, v_2, v_3, v_4)
+    >>> graph.add_edge('v_1', 'v_2')
+    >>> graph.add_edge('v_2', 'v_3')
+    >>> graph.add_edge('v_4', 'v_1')
+    >>> maximum_matching(graph, 'hopcroft_karp')
+    >>> {('v_1', 'v_4'), ('v_3', 'v_2')}
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Hopcroft%E2%80%93Karp_algorithm
+    """
+
+
+    raise_if_backend_is_not_python(
+        maximum_matching, kwargs.get('backend', Backend.PYTHON))
+    make_undirected = kwargs.get('make_undirected', False)
+    if make_undirected:
+        graph = graph.to_undirected_adjacency_list()
+
+    import pydatastructs.graphs.algorithms as algorithms
+    func = "_maximum_matching_" + algorithm + "_"
+    if not hasattr(algorithms, func):
+        raise NotImplementedError(
+        f"Currently {algorithm} algorithm isn't implemented for "
+        "finding maximum matching in graphs.")
+    return getattr(algorithms, func)(graph)
+
+def _maximum_matching_hopcroft_karp_parallel(graph: Graph, num_threads: int) -> set:
+    U = set()
+    V = set()
+    bipartiteness, coloring = bipartite_coloring(graph)
+
+    if not bipartiteness:
+        raise ValueError("Graph is not bipartite.")
+
+    for node, c in coloring.items():
+        if c == 0:
+            U.add(node)
+        else:
+            V.add(node)
+
+
+    pair_U = {u: None for u in U}
+    pair_V = {v: None for v in V}
+    dist = {}
+
+    def bfs():
+        queue = Queue()
+        for u in U:
+            if pair_U[u] is None:
+                dist[u] = 0
+                queue.append(u)
+            else:
+                dist[u] = float('inf')
+        dist[None] = float('inf')
+        while queue:
+            u = queue.popleft()
+            if dist[u] < dist[None]:
+                for v in graph.neighbors(u):
+                    if dist[pair_V[v.name]] == float('inf'):
+                        dist[pair_V[v.name]] = dist[u] + 1
+                        queue.append(pair_V[v.name])
+        return dist[None] != float('inf')
+
+    def dfs(u):
+        if u is not None:
+            for v in graph.neighbors(u):
+                if dist[pair_V[v.name]] == dist[u] + 1:
+                    if dfs(pair_V[v.name]):
+                        pair_V[v.name] = u
+                        pair_U[u] = v.name
+                        return True
+            dist[u] = float('inf')
+            return False
+        return True
+
+    matching = set()
+
+    while bfs():
+        unmatched_nodes = [u for u in U if pair_U[u] is None]
+
+        with ThreadPoolExecutor(max_workers=num_threads) as Executor:
+            results = Executor.map(dfs, unmatched_nodes)
+
+        for u, success in zip(unmatched_nodes, results):
+            if success:
+                matching.add((u, pair_U[u]))
+
+    return matching
+
+
+def maximum_matching_parallel(graph: Graph, algorithm: str, num_threads: int, **kwargs):
+    """
+    Finds the maximum matching in the given graph using the given algorithm using
+    the given number of threads.
+
+    Parameters
+    ==========
+
+    graph: Graph
+        The graph under consideration.
+    algorithm: str
+        The algorithm to be used.
+        Currently, following are supported,
+
+        'hopcroft_karp' -> Hopcroft-Karp algorithm for Bipartite Graphs as given in [1].
+    num_threads: int
+        The maximum number of threads to be used.
+    backend: pydatastructs.Backend
+        The backend to be used.
+        Optional, by default, the best available
+        backend is used.
+
+    Returns
+    =======
+
+    set
+        The set of edges which form the maximum matching.
+
+    Examples
+    ========
+
+    >>> from pydatastructs import Graph, AdjacencyListGraphNode, maximum_matching_parallel
+    >>> v_1 = AdjacencyListGraphNode('v_1')
+    >>> v_2 = AdjacencyListGraphNode('v_2')
+    >>> v_3 = AdjacencyListGraphNode('v_3')
+    >>> v_4 = AdjacencyListGraphNode('v_4')
+    >>> graph = Graph(v_1, v_2, v_3, v_4)
+    >>> graph.add_bidirectional_edge('v_1', 'v_2')
+    >>> graph.add_bidirectional_edge('v_2', 'v_3')
+    >>> graph.add_bidirectional_edge('v_4', 'v_1')
+    >>> maximum_matching_parallel(graph, 'hopcroft_karp', 1)
+    >>> {('v_1', 'v_4'), ('v_3', 'v_2')}
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Hopcroft%E2%80%93Karp_algorithm
+    """
+
+    raise_if_backend_is_not_python(
+        maximum_matching_parallel, kwargs.get('backend', Backend.PYTHON))
+
+    import pydatastructs.graphs.algorithms as algorithms
+    func = "_maximum_matching_" + algorithm + "_parallel"
+    if not hasattr(algorithms, func):
+        raise NotImplementedError(
+        f"Currently {algorithm} algorithm isn't implemented for "
+        "finding maximum matching in graphs.")
+    return getattr(algorithms, func)(graph, num_threads)

pydatastructs/graphs/graph.py

@@ -161,3 +161,28 @@ def num_edges(self):
         """
         raise NotImplementedError(
             "This is an abstract method.")
+
+    def add_bidirectional_edge(self, node1, node2, cost=None):
+        """
+        Adds edges between node1 and node2 in both directions.
+        """
+        self.add_edge(node1, node2, cost)
+        self.add_edge(node2, node1, cost)
+
+    def to_undirected_adjacency_list(self):
+        """
+        Converts the graph to undirected graph.
+        """
+        vertexes = []
+        undirected_graph = Graph(implementation='adjacency_list')
+        for vertex in self.vertices:
+            undirected_graph.add_vertex(
+                self.__getattribute__(vertex)
+            )
+
+        for vertex in self.vertices:
+            for v in self.neighbors(vertex):
+                edge = self.get_edge(vertex, v.name)
+                undirected_graph.add_bidirectional_edge(vertex, v.name, edge)
+
+        return undirected_graph