Add Hopcroft-Karp algorithm and tests

Author: ptzecher

src/main/java/com/thealgorithms/dynamicprogramming/PartitionProblem.java

@@ -1,3 +1,10 @@
+
+
+package com.thealgorithms.dynamicprogramming;
+
+import java.util.Arrays;
+
+
 /**
  * @author Md Asif Joardar
  *
@@ -14,10 +21,6 @@
  * The time complexity of the solution is O(n × sum) and requires O(n × sum) space
  */
 
-package com.thealgorithms.dynamicprogramming;
-
-import java.util.Arrays;
-
 public final class PartitionProblem {
     private PartitionProblem() {
     }

src/main/java/com/thealgorithms/graph/HopcroftKarp.java

@@ -0,0 +1,99 @@
+package com.thealgorithms.graph;
+
+import java.util.*;
+
+/**
+ * @author Panteleimon Tzecheridis
+ * Implementation of the Hopcroft–Karp algorithm for finding the maximum matching in a bipartite graph.
+ *
+ * The bipartite graph is assumed to have:
+ * - Left part: vertices [0..nLeft-1]
+ * - Right part: vertices [0..nRight-1]
+ *
+ * Adjacency list format: For each left vertex, list the right vertices it is connected to.
+ * Example:
+ *   adj[0] = [0, 1]  // left vertex 0 connects to right vertices 0 and 1
+ *
+ * Time complexity: O(E * sqrt(V))
+ */
+public class HopcroftKarp {
+
+    private int nLeft, nRight;
+    private List<List<Integer>> adj;
+    private int[] pairU, pairV, dist;
+
+    public HopcroftKarp(int nLeft, int nRight, List<List<Integer>> adj) {
+        this.nLeft = nLeft;
+        this.nRight = nRight;
+        this.adj = adj;
+        this.pairU = new int[nLeft];
+        this.pairV = new int[nRight];
+        this.dist = new int[nLeft];
+        Arrays.fill(pairU, -1);
+        Arrays.fill(pairV, -1);
+    }
+
+    /**
+     * Returns the size of the maximum matching.
+     */
+    public int maxMatching() {
+        int matching = 0;
+        while (bfs()) {
+            for (int u = 0; u < nLeft; u++) {
+                if (pairU[u] == -1 && dfs(u)) {
+                    matching++;
+                }
+            }
+        }
+        return matching;
+    }
+
+    // BFS to build layers
+    private boolean bfs() {
+        Queue<Integer> queue = new ArrayDeque<>();
+        Arrays.fill(dist, -1);
+        for (int u = 0; u < nLeft; u++) {
+            if (pairU[u] == -1) {
+                dist[u] = 0;
+                queue.add(u);
+            }
+        }
+        boolean foundAugPath = false;
+        while (!queue.isEmpty()) {
+            int u = queue.poll();
+            for (int v : adj.get(u)) {
+                int u2 = pairV[v];
+                if (u2 == -1) {
+                    foundAugPath = true;
+                } else if (dist[u2] == -1) {
+                    dist[u2] = dist[u] + 1;
+                    queue.add(u2);
+                }
+            }
+        }
+        return foundAugPath;
+    }
+
+    // DFS to find augmenting paths
+    private boolean dfs(int u) {
+        for (int v : adj.get(u)) {
+            int u2 = pairV[v];
+            if (u2 == -1 || (dist[u2] == dist[u] + 1 && dfs(u2))) {
+                pairU[u] = v;
+                pairV[v] = u;
+                return true;
+            }
+        }
+        dist[u] = -1;
+        return false;
+    }
+
+    public int[] getLeftMatches() {
+        return pairU.clone();
+    }
+
+    public int[] getRightMatches() {
+        return pairV.clone();
+    }
+
+}

src/test/java/com/thealgorithms/graph/HopcroftKarpTest.java

@@ -0,0 +1,129 @@
+package com.thealgorithms.graph;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+class HopcroftKarpTest {
+
+    private static List<List<Integer>> adj(int nLeft) {
+        List<List<Integer>> g = new ArrayList<>(nLeft);
+        for (int i = 0; i < nLeft; i++) g.add(new ArrayList<>());
+        return g;
+    }
+
+    @Test
+    @DisplayName("Empty graph has matching 0")
+    void emptyGraph() {
+        List<List<Integer>> g = adj(3);
+        HopcroftKarp hk = new HopcroftKarp(3, 4, g);
+        assertEquals(0, hk.maxMatching());
+    }
+
+    @Test
+    @DisplayName("Single edge gives matching 1")
+    void singleEdge() {
+        List<List<Integer>> g = adj(1);
+        g.get(0).add(0);
+        HopcroftKarp hk = new HopcroftKarp(1, 1, g);
+        assertEquals(1, hk.maxMatching());
+
+        int[] L = hk.getLeftMatches();
+        int[] R = hk.getRightMatches();
+        assertEquals(0, L[0]);
+        assertEquals(0, R[0]);
+    }
+
+    @Test
+    @DisplayName("Disjoint edges match perfectly")
+    void disjointEdges() {
+        // L0-R0, L1-R1, L2-R2
+        List<List<Integer>> g = adj(3);
+        g.get(0).add(0);
+        g.get(1).add(1);
+        g.get(2).add(2);
+
+        HopcroftKarp hk = new HopcroftKarp(3, 3, g);
+        assertEquals(3, hk.maxMatching());
+
+        int[] L = hk.getLeftMatches();
+        int[] R = hk.getRightMatches();
+        for (int i = 0; i < 3; i++) {
+            assertEquals(i, L[i]);
+            assertEquals(i, R[i]);
+        }
+    }
+
+    @Test
+    @DisplayName("Complete bipartite K(3,4) matches min(3,4)=3")
+    void completeK34() {
+        int nLeft = 3, nRight = 4;
+        List<List<Integer>> g = adj(nLeft);
+        for (int u = 0; u < nLeft; u++) {
+            g.get(u).addAll(Arrays.asList(0, 1, 2, 3));
+        }
+        HopcroftKarp hk = new HopcroftKarp(nLeft, nRight, g);
+        assertEquals(3, hk.maxMatching());
+
+        // sanity: no two left vertices share the same matched right vertex
+        int[] L = hk.getLeftMatches();
+        boolean[] used = new boolean[nRight];
+        for (int u = 0; u < nLeft; u++) {
+            int v = L[u];
+            if (v != -1) {
+                assertFalse(used[v]);
+                used[v] = true;
+            }
+        }
+    }
+
+    @Test
+    @DisplayName("Non-square, sparse graph")
+    void rectangularSparse() {
+        // Left: 5, Right: 2
+        // edges: L0-R0, L1-R1, L2-R0, L3-R1 (max matching = 2)
+        List<List<Integer>> g = adj(5);
+        g.get(0).add(0);
+        g.get(1).add(1);
+        g.get(2).add(0);
+        g.get(3).add(1);
+        // L4 isolated
+
+        HopcroftKarp hk = new HopcroftKarp(5, 2, g);
+        assertEquals(2, hk.maxMatching());
+
+        int[] L = hk.getLeftMatches();
+        int[] R = hk.getRightMatches();
+
+        // Check consistency: if L[u]=v then R[v]=u
+        for (int u = 0; u < 5; u++) {
+            int v = L[u];
+            if (v != -1) {
+                assertEquals(u, R[v]);
+            }
+        }
+    }
+
+    @Test
+    @DisplayName("Layering advantage case (chains of short augmenting paths)")
+    void layeringAdvantage() {
+        // Left 4, Right 4
+        // Build a structure that benefits from BFS layering
+        // L0: R0, R1
+        // L1: R1, R2
+        // L2: R2, R3
+        // L3: R0, R3
+        List<List<Integer>> g = adj(4);
+        g.get(0).addAll(Arrays.asList(0, 1));
+        g.get(1).addAll(Arrays.asList(1, 2));
+        g.get(2).addAll(Arrays.asList(2, 3));
+        g.get(3).addAll(Arrays.asList(0, 3));
+
+        HopcroftKarp hk = new HopcroftKarp(4, 4, g);
+        assertEquals(4, hk.maxMatching()); // perfect matching exists
+    }
+}