Merge branch 'main' into matching-algorithm

Author: Akshat-Shu

docs/source/pydatastructs/graphs/algorithms.rst

@@ -20,3 +20,5 @@ Algorithms
 .. autofunction:: pydatastructs.topological_sort
 
 .. autofunction:: pydatastructs.topological_sort_parallel
+
+.. autofunction:: pydatastructs.find_bridges

pydatastructs/graphs/__init__.py

@@ -24,7 +24,8 @@
     max_flow,
     maximum_matching,
     maximum_matching_parallel,
-    bipartite_coloring
+    bipartite_coloring,
+    find_bridges
 )
 
 __all__.extend(algorithms.__all__)

pydatastructs/graphs/algorithms.py

@@ -29,7 +29,8 @@
     'max_flow',
     'maximum_matching',
     'maximum_matching_parallel',
-    'bipartite_coloring'
+    'bipartite_coloring',
+    'find_bridges'
 ]
 
 Stack = Queue = deque
@@ -536,6 +537,52 @@ def _strongly_connected_components_kosaraju_adjacency_list(graph):
 _strongly_connected_components_kosaraju_adjacency_matrix = \
     _strongly_connected_components_kosaraju_adjacency_list
 
+def _tarjan_dfs(u, graph, index, stack, indices, low_links, on_stacks, components):
+    indices[u] = index[0]
+    low_links[u] = index[0]
+    index[0] += 1
+    stack.append(u)
+    on_stacks[u] = True
+
+    for node in graph.neighbors(u):
+        v = node.name
+        if indices[v] == -1:
+            _tarjan_dfs(v, graph, index, stack, indices, low_links, on_stacks, components)
+            low_links[u] = min(low_links[u], low_links[v])
+        elif on_stacks[v]:
+            low_links[u] = min(low_links[u], low_links[v])
+
+    if low_links[u] == indices[u]:
+        component = set()
+        while stack:
+            w = stack.pop()
+            on_stacks[w] = False
+            component.add(w)
+            if w == u:
+                break
+        components.append(component)
+
+def _strongly_connected_components_tarjan_adjacency_list(graph):
+    index = [0] # mutable object
+    stack = Stack([])
+    indices, low_links, on_stacks = {}, {}, {}
+
+    for u in graph.vertices:
+        indices[u] = -1
+        low_links[u] = -1
+        on_stacks[u] = False
+
+    components = []
+
+    for u in graph.vertices:
+        if indices[u] == -1:
+            _tarjan_dfs(u, graph, index, stack, indices, low_links, on_stacks, components)
+
+    return components
+
+_strongly_connected_components_tarjan_adjacency_matrix = \
+    _strongly_connected_components_tarjan_adjacency_list
+
 def strongly_connected_components(graph, algorithm, **kwargs):
     """
     Computes strongly connected components for the given
@@ -554,6 +601,7 @@ def strongly_connected_components(graph, algorithm, **kwargs):
         supported,
 
         'kosaraju' -> Kosaraju's algorithm as given in [1].
+        'tarjan' -> Tarjan's algorithm as given in [2].
     backend: pydatastructs.Backend
         The backend to be used.
         Optional, by default, the best available
@@ -583,6 +631,7 @@ def strongly_connected_components(graph, algorithm, **kwargs):
     ==========
 
     .. [1] https://en.wikipedia.org/wiki/Kosaraju%27s_algorithm
+    .. [2] https://en.wikipedia.org/wiki/Tarjan%27s_strongly_connected_components_algorithm
 
     """
     raise_if_backend_is_not_python(
@@ -1223,6 +1272,7 @@ def max_flow(graph, source, sink, algorithm='edmonds_karp', **kwargs):
         "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.
@@ -1265,6 +1315,7 @@ def bipartite_coloring(graph: Graph, **kwargs) -> Tuple[bool, Dict]:
     >>> bipartite_coloring(graph, make_undirected=True)
     (True, {'v_1': 0, 'v_2': 1, 'v_4': 1, 'v_3': 0})
 
+
     References
     ==========
 
@@ -1615,3 +1666,101 @@ def maximum_matching_parallel(graph: Graph, algorithm: str, num_threads: int, **
         f"Currently {algorithm} algorithm isn't implemented for "
         "finding maximum matching in graphs.")
     return getattr(algorithms, func)(graph, num_threads)
+
+def find_bridges(graph):
+    """
+    Finds all bridges in an undirected graph using Tarjan's Algorithm.
+
+    Parameters
+    ==========
+    graph : Graph
+        An undirected graph instance.
+
+    Returns
+    ==========
+    List[tuple]
+        A list of bridges, where each bridge is represented as a tuple (u, v)
+        with u <= v.
+
+    Example
+    ========
+    >>> from pydatastructs import Graph, AdjacencyListGraphNode, find_bridges
+    >>> v0 = AdjacencyListGraphNode(0)
+    >>> v1 = AdjacencyListGraphNode(1)
+    >>> v2 = AdjacencyListGraphNode(2)
+    >>> v3 = AdjacencyListGraphNode(3)
+    >>> v4 = AdjacencyListGraphNode(4)
+    >>> graph = Graph(v0, v1, v2, v3, v4, implementation='adjacency_list')
+    >>> graph.add_edge(v0.name, v1.name)
+    >>> graph.add_edge(v1.name, v2.name)
+    >>> graph.add_edge(v2.name, v3.name)
+    >>> graph.add_edge(v3.name, v4.name)
+    >>> find_bridges(graph)
+    [('0', '1'), ('1', '2'), ('2', '3'), ('3', '4')]
+    .. [1] https://en.wikipedia.org/wiki/Bridge_(graph_theory)
+    """
+
+    vertices = list(graph.vertices)
+    processed_vertices = []
+    for v in vertices:
+        if hasattr(v, "name"):
+            processed_vertices.append(v.name)
+        else:
+            processed_vertices.append(v)
+
+    n = len(processed_vertices)
+    adj = {v: [] for v in processed_vertices}
+    for v in processed_vertices:
+        for neighbor in graph.neighbors(v):
+            if hasattr(neighbor, "name"):
+                nbr = neighbor.name
+            else:
+                nbr = neighbor
+            adj[v].append(nbr)
+
+    mapping = {v: idx for idx, v in enumerate(processed_vertices)}
+    inv_mapping = {idx: v for v, idx in mapping.items()}
+
+    n_adj = [[] for _ in range(n)]
+    for v in processed_vertices:
+        idx_v = mapping[v]
+        for u in adj[v]:
+            idx_u = mapping[u]
+            n_adj[idx_v].append(idx_u)
+
+    visited = [False] * n
+    disc = [0] * n
+    low = [0] * n
+    parent = [-1] * n
+    bridges_idx = []
+    time = 0
+
+    def dfs(u):
+        nonlocal time
+        visited[u] = True
+        disc[u] = low[u] = time
+        time += 1
+        for v in n_adj[u]:
+            if not visited[v]:
+                parent[v] = u
+                dfs(v)
+                low[u] = min(low[u], low[v])
+                if low[v] > disc[u]:
+                    bridges_idx.append((u, v))
+            elif v != parent[u]:
+                low[u] = min(low[u], disc[v])
+
+    for i in range(n):
+        if not visited[i]:
+            dfs(i)
+
+    bridges = []
+    for u, v in bridges_idx:
+        a = inv_mapping[u]
+        b = inv_mapping[v]
+        if a <= b:
+            bridges.append((a, b))
+        else:
+            bridges.append((b, a))
+    bridges.sort()
+    return bridges

pydatastructs/graphs/tests/test_algorithms.py

@@ -2,7 +2,8 @@
 breadth_first_search_parallel, minimum_spanning_tree,
 minimum_spanning_tree_parallel, strongly_connected_components,
 depth_first_search, shortest_paths,all_pair_shortest_paths, topological_sort,
-topological_sort_parallel, max_flow, maximum_matching, maximum_matching_parallel, bipartite_coloring)
+topological_sort_parallel, max_flow, maximum_matching, maximum_matching_parallel,
+bipartite_coloring, find_bridges)
 from pydatastructs.utils.raises_util import raises
 
 def test_breadth_first_search():
@@ -188,11 +189,13 @@ def _test_strongly_connected_components(func, ds, algorithm, *args):
         graph.add_edge(h.name, g.name)
         comps = func(graph, algorithm)
         expected_comps = [{'e', 'a', 'b'}, {'d', 'c', 'h'}, {'g', 'f'}]
-        assert comps == expected_comps
+        assert comps.sort() == expected_comps.sort()
 
     scc = strongly_connected_components
     _test_strongly_connected_components(scc, "List", "kosaraju")
     _test_strongly_connected_components(scc, "Matrix", "kosaraju")
+    _test_strongly_connected_components(scc, "List", "tarjan")
+    _test_strongly_connected_components(scc, "Matrix", "tarjan")
 
 def test_depth_first_search():
 
@@ -449,8 +452,6 @@ def _test_max_flow(ds, algorithm):
     _test_max_flow("List", "dinic")
     _test_max_flow("Matrix", "dinic")
 
-
-
 def test_maximum_matching():
     def _test_maximum_matching(func, ds, algorithm, **kwargs):
         import pydatastructs.utils.misc_util as utils
@@ -621,3 +622,56 @@ def _test_bipartite_coloring(ds):
 
         assert valid
         assert _assert_correctness(G3, coloring)
+
+def test_find_bridges():
+    def _test_find_bridges(ds):
+        import pydatastructs.utils.misc_util as utils
+        GraphNode = getattr(utils, "Adjacency" + ds + "GraphNode")
+
+        impl = 'adjacency_list' if ds == "List" else 'adjacency_matrix'
+
+        v0 = GraphNode(0)
+        v1 = GraphNode(1)
+        v2 = GraphNode(2)
+        v3 = GraphNode(3)
+        v4 = GraphNode(4)
+
+        G1 = Graph(v0, v1, v2, v3, v4, implementation=impl)
+        G1.add_edge(v0.name, v1.name)
+        G1.add_edge(v1.name, v2.name)
+        G1.add_edge(v2.name, v3.name)
+        G1.add_edge(v3.name, v4.name)
+
+        bridges = find_bridges(G1)
+        expected_bridges = [('0', '1'), ('1', '2'), ('2', '3'), ('3', '4')]
+        assert sorted(bridges) == sorted(expected_bridges)
+
+        u0 = GraphNode(0)
+        u1 = GraphNode(1)
+        u2 = GraphNode(2)
+
+        G2 = Graph(u0, u1, u2, implementation=impl)
+        G2.add_edge(u0.name, u1.name)
+        G2.add_edge(u1.name, u2.name)
+        G2.add_edge(u2.name, u0.name)
+
+        bridges = find_bridges(G2)
+        assert bridges == []
+
+        w0 = GraphNode(0)
+        w1 = GraphNode(1)
+        w2 = GraphNode(2)
+        w3 = GraphNode(3)
+        w4 = GraphNode(4)
+
+        G3 = Graph(w0, w1, w2, w3, w4, implementation=impl)
+        G3.add_edge(w0.name, w1.name)
+        G3.add_edge(w1.name, w2.name)
+        G3.add_edge(w3.name, w4.name)
+
+        bridges = find_bridges(G3)
+        expected_bridges = [('0', '1'), ('1', '2'), ('3', '4')]
+        assert sorted(bridges) == sorted(expected_bridges)
+
+    _test_find_bridges("List")
+    _test_find_bridges("Matrix")