Merge branch 'master' into feat-stoer-wagner

Author: sairamsharan

DIRECTORY.md

@@ -372,6 +372,7 @@
           - 📄 [Edmonds](src/main/java/com/thealgorithms/graph/Edmonds.java)
           - 📄 [EdmondsKarp](src/main/java/com/thealgorithms/graph/EdmondsKarp.java)
           - 📄 [HopcroftKarp](src/main/java/com/thealgorithms/graph/HopcroftKarp.java)
+          - 📄 [HungarianAlgorithm](src/main/java/com/thealgorithms/graph/HungarianAlgorithm.java)
           - 📄 [PredecessorConstrainedDfs](src/main/java/com/thealgorithms/graph/PredecessorConstrainedDfs.java)
           - 📄 [PushRelabel](src/main/java/com/thealgorithms/graph/PushRelabel.java)
           - 📄 [StronglyConnectedComponentOptimized](src/main/java/com/thealgorithms/graph/StronglyConnectedComponentOptimized.java)

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

@@ -0,0 +1,150 @@
+package com.thealgorithms.graph;
+
+import java.util.Arrays;
+
+/**
+ * Hungarian algorithm (a.k.a. Kuhn–Munkres) for the Assignment Problem.
+ *
+ * <p>Given an n x m cost matrix (n tasks, m workers), finds a minimum-cost
+ * one-to-one assignment. If the matrix is rectangular, the algorithm pads to a
+ * square internally. Costs must be finite non-negative integers.
+ *
+ * <p>Time complexity: O(n^3) with n = max(rows, cols).
+ *
+ * <p>API returns the assignment as an array where {@code assignment[i]} is the
+ * column chosen for row i (or -1 if unassigned when rows != cols), and a total
+ * minimal cost.
+ *
+ * @see <a href="https://en.wikipedia.org/wiki/Hungarian_algorithm">Wikipedia: Hungarian algorithm</a>
+ */
+public final class HungarianAlgorithm {
+
+    private HungarianAlgorithm() {
+    }
+
+    /** Result holder for the Hungarian algorithm. */
+    public static final class Result {
+        public final int[] assignment; // assignment[row] = col or -1
+        public final int minCost;
+
+        public Result(int[] assignment, int minCost) {
+            this.assignment = assignment;
+            this.minCost = minCost;
+        }
+    }
+
+    /**
+     * Solves the assignment problem for a non-negative cost matrix.
+     *
+     * @param cost an r x c matrix of non-negative costs
+     * @return Result with row-to-column assignment and minimal total cost
+     * @throws IllegalArgumentException for null/empty or negative costs
+     */
+    public static Result solve(int[][] cost) {
+        validate(cost);
+        int rows = cost.length;
+        int cols = cost[0].length;
+        int n = Math.max(rows, cols);
+
+        // Build square matrix with padding 0 for missing cells
+        int[][] a = new int[n][n];
+        for (int i = 0; i < n; i++) {
+            if (i < rows) {
+                for (int j = 0; j < n; j++) {
+                    a[i][j] = (j < cols) ? cost[i][j] : 0;
+                }
+            } else {
+                Arrays.fill(a[i], 0);
+            }
+        }
+
+        // Potentials and matching arrays
+        int[] u = new int[n + 1];
+        int[] v = new int[n + 1];
+        int[] p = new int[n + 1];
+        int[] way = new int[n + 1];
+
+        for (int i = 1; i <= n; i++) {
+            p[0] = i;
+            int j0 = 0;
+            int[] minv = new int[n + 1];
+            boolean[] used = new boolean[n + 1];
+            Arrays.fill(minv, Integer.MAX_VALUE);
+            Arrays.fill(used, false);
+            do {
+                used[j0] = true;
+                int i0 = p[j0];
+                int delta = Integer.MAX_VALUE;
+                int j1 = 0;
+                for (int j = 1; j <= n; j++) {
+                    if (!used[j]) {
+                        int cur = a[i0 - 1][j - 1] - u[i0] - v[j];
+                        if (cur < minv[j]) {
+                            minv[j] = cur;
+                            way[j] = j0;
+                        }
+                        if (minv[j] < delta) {
+                            delta = minv[j];
+                            j1 = j;
+                        }
+                    }
+                }
+                for (int j = 0; j <= n; j++) {
+                    if (used[j]) {
+                        u[p[j]] += delta;
+                        v[j] -= delta;
+                    } else {
+                        minv[j] -= delta;
+                    }
+                }
+                j0 = j1;
+            } while (p[j0] != 0);
+            do {
+                int j1 = way[j0];
+                p[j0] = p[j1];
+                j0 = j1;
+            } while (j0 != 0);
+        }
+
+        int[] matchColForRow = new int[n];
+        Arrays.fill(matchColForRow, -1);
+        for (int j = 1; j <= n; j++) {
+            if (p[j] != 0) {
+                matchColForRow[p[j] - 1] = j - 1;
+            }
+        }
+
+        // Build assignment for original rows only, ignore padded rows
+        int[] assignment = new int[rows];
+        Arrays.fill(assignment, -1);
+        int total = 0;
+        for (int i = 0; i < rows; i++) {
+            int j = matchColForRow[i];
+            if (j >= 0 && j < cols) {
+                assignment[i] = j;
+                total += cost[i][j];
+            }
+        }
+        return new Result(assignment, total);
+    }
+
+    private static void validate(int[][] cost) {
+        if (cost == null || cost.length == 0) {
+            throw new IllegalArgumentException("Cost matrix must not be null or empty");
+        }
+        int c = cost[0].length;
+        if (c == 0) {
+            throw new IllegalArgumentException("Cost matrix must have at least 1 column");
+        }
+        for (int i = 0; i < cost.length; i++) {
+            if (cost[i] == null || cost[i].length != c) {
+                throw new IllegalArgumentException("Cost matrix must be rectangular with equal row lengths");
+            }
+            for (int j = 0; j < c; j++) {
+                if (cost[i][j] < 0) {
+                    throw new IllegalArgumentException("Costs must be non-negative");
+                }
+            }
+        }
+    }
+}

src/main/java/com/thealgorithms/others/MaximumSumOfDistinctSubarraysWithLengthK.java

@@ -1,69 +1,89 @@
 package com.thealgorithms.others;
 
-import java.util.HashSet;
-import java.util.Set;
+import java.util.HashMap;
+import java.util.Map;
 
 /**
- * References: https://en.wikipedia.org/wiki/Streaming_algorithm
+ * Algorithm to find the maximum sum of a subarray of size K with all distinct
+ * elements.
  *
- * This model involves computing the maximum sum of subarrays of a fixed size \( K \) from a stream of integers.
- * As the stream progresses, elements from the end of the window are removed, and new elements from the stream are added.
+ * This implementation uses a sliding window approach with a hash map to
+ * efficiently
+ * track element frequencies within the current window. The algorithm maintains
+ * a window
+ * of size K and slides it across the array, ensuring all elements in the window
+ * are distinct.
  *
+ * Time Complexity: O(n) where n is the length of the input array
+ * Space Complexity: O(k) for storing elements in the hash map
+ *
+ * @see <a href="https://en.wikipedia.org/wiki/Streaming_algorithm">Streaming
+ *      Algorithm</a>
+ * @see <a href="https://en.wikipedia.org/wiki/Sliding_window_protocol">Sliding
+ *      Window</a>
  * @author Swarga-codes (https://github.com/Swarga-codes)
  */
 public final class MaximumSumOfDistinctSubarraysWithLengthK {
     private MaximumSumOfDistinctSubarraysWithLengthK() {
     }
 
     /**
-     * Finds the maximum sum of a subarray of size K consisting of distinct elements.
+     * Finds the maximum sum of a subarray of size K consisting of distinct
+     * elements.
      *
-     * @param k The size of the subarray.
-     * @param nums The array from which subarrays will be considered.
+     * The algorithm uses a sliding window technique with a frequency map to track
+     * the count of each element in the current window. A window is valid only if
+     * all K elements are distinct (frequency map size equals K).
      *
-     * @return The maximum sum of any distinct-element subarray of size K. If no such subarray exists, returns 0.
+     * @param k    The size of the subarray. Must be non-negative.
+     * @param nums The array from which subarrays will be considered.
+     * @return The maximum sum of any distinct-element subarray of size K.
+     *         Returns 0 if no such subarray exists or if k is 0 or negative.
+     * @throws IllegalArgumentException if k is negative
      */
     public static long maximumSubarraySum(int k, int... nums) {
-        if (nums.length < k) {
+        if (k <= 0 || nums == null || nums.length < k) {
             return 0;
         }
-        long masSum = 0; // Variable to store the maximum sum of distinct subarrays
-        long currentSum = 0; // Variable to store the sum of the current subarray
-        Set<Integer> currentSet = new HashSet<>(); // Set to track distinct elements in the current subarray
 
-        // Initialize the first window
+        long maxSum = 0;
+        long currentSum = 0;
+        Map<Integer, Integer> frequencyMap = new HashMap<>();
+
+        // Initialize the first window of size k
         for (int i = 0; i < k; i++) {
             currentSum += nums[i];
-            currentSet.add(nums[i]);
+            frequencyMap.put(nums[i], frequencyMap.getOrDefault(nums[i], 0) + 1);
         }
-        // If the first window contains distinct elements, update maxSum
-        if (currentSet.size() == k) {
-            masSum = currentSum;
+
+        // Check if the first window has all distinct elements
+        if (frequencyMap.size() == k) {
+            maxSum = currentSum;
         }
+
         // Slide the window across the array
-        for (int i = 1; i < nums.length - k + 1; i++) {
-            // Update the sum by removing the element that is sliding out and adding the new element
-            currentSum = currentSum - nums[i - 1];
-            currentSum = currentSum + nums[i + k - 1];
-            int j = i;
-            boolean flag = false; // flag value which says that the subarray contains distinct elements
-            while (j < i + k && currentSet.size() < k) {
-                if (nums[i - 1] == nums[j]) {
-                    flag = true;
-                    break;
-                } else {
-                    j++;
-                }
-            }
-            if (!flag) {
-                currentSet.remove(nums[i - 1]);
+        for (int i = k; i < nums.length; i++) {
+            // Remove the leftmost element from the window
+            int leftElement = nums[i - k];
+            currentSum -= leftElement;
+            int leftFrequency = frequencyMap.get(leftElement);
+            if (leftFrequency == 1) {
+                frequencyMap.remove(leftElement);
+            } else {
+                frequencyMap.put(leftElement, leftFrequency - 1);
             }
-            currentSet.add(nums[i + k - 1]);
-            // If the current window has distinct elements, compare and possibly update maxSum
-            if (currentSet.size() == k && masSum < currentSum) {
-                masSum = currentSum;
+
+            // Add the new rightmost element to the window
+            int rightElement = nums[i];
+            currentSum += rightElement;
+            frequencyMap.put(rightElement, frequencyMap.getOrDefault(rightElement, 0) + 1);
+
+            // If all elements in the window are distinct, update maxSum if needed
+            if (frequencyMap.size() == k && currentSum > maxSum) {
+                maxSum = currentSum;
             }
         }
-        return masSum; // the final maximum sum
+
+        return maxSum;
     }
 }

src/main/java/com/thealgorithms/physics/DampedOscillator.java

@@ -0,0 +1,109 @@
+package com.thealgorithms.physics;
+
+/**
+ * Models a damped harmonic oscillator, capturing the behavior of a mass-spring-damper system.
+ *
+ * <p>The system is defined by the second-order differential equation:
+ *     x'' + 2 * gamma * x' + omega₀² * x = 0
+ * where:
+ * <ul>
+ *   <li><b>omega₀</b> is the natural (undamped) angular frequency in radians per second.</li>
+ *   <li><b>gamma</b> is the damping coefficient in inverse seconds.</li>
+ * </ul>
+ *
+ * <p>This implementation provides:
+ * <ul>
+ *   <li>An analytical solution for the underdamped case (γ < ω₀).</li>
+ *   <li>A numerical integrator based on the explicit Euler method for simulation purposes.</li>
+ * </ul>
+ *
+ * <p><strong>Usage Example:</strong>
+ * <pre>{@code
+ * DampedOscillator oscillator = new DampedOscillator(10.0, 0.5);
+ * double displacement = oscillator.displacementAnalytical(1.0, 0.0, 0.1);
+ * double[] nextState = oscillator.stepEuler(new double[]{1.0, 0.0}, 0.001);
+ * }</pre>
+ *
+ * @author [Yash Rajput](https://github.com/the-yash-rajput)
+ */
+public final class DampedOscillator {
+
+    /** Natural (undamped) angular frequency (rad/s). */
+    private final double omega0;
+
+    /** Damping coefficient (s⁻¹). */
+    private final double gamma;
+
+    private DampedOscillator() {
+        throw new AssertionError("No instances.");
+    }
+
+    /**
+     * Constructs a damped oscillator model.
+     *
+     * @param omega0 the natural frequency (rad/s), must be positive
+     * @param gamma  the damping coefficient (s⁻¹), must be non-negative
+     * @throws IllegalArgumentException if parameters are invalid
+     */
+    public DampedOscillator(double omega0, double gamma) {
+        if (omega0 <= 0) {
+            throw new IllegalArgumentException("Natural frequency must be positive.");
+        }
+        if (gamma < 0) {
+            throw new IllegalArgumentException("Damping coefficient must be non-negative.");
+        }
+        this.omega0 = omega0;
+        this.gamma = gamma;
+    }
+
+    /**
+     * Computes the analytical displacement of an underdamped oscillator.
+     * Formula: x(t) = A * exp(-γt) * cos(ω_d t + φ)
+     *
+     * @param amplitude the initial amplitude A
+     * @param phase     the initial phase φ (radians)
+     * @param time      the time t (seconds)
+     * @return the displacement x(t)
+     */
+    public double displacementAnalytical(double amplitude, double phase, double time) {
+        double omegaD = Math.sqrt(Math.max(0.0, omega0 * omega0 - gamma * gamma));
+        return amplitude * Math.exp(-gamma * time) * Math.cos(omegaD * time + phase);
+    }
+
+    /**
+     * Performs a single integration step using the explicit Euler method.
+     * State vector format: [x, v], where v = dx/dt.
+     *
+     * @param state the current state [x, v]
+     * @param dt    the time step (seconds)
+     * @return the next state [x_next, v_next]
+     * @throws IllegalArgumentException if the state array is invalid or dt is non-positive
+     */
+    public double[] stepEuler(double[] state, double dt) {
+        if (state == null || state.length != 2) {
+            throw new IllegalArgumentException("State must be a non-null array of length 2.");
+        }
+        if (dt <= 0) {
+            throw new IllegalArgumentException("Time step must be positive.");
+        }
+
+        double x = state[0];
+        double v = state[1];
+        double acceleration = -2.0 * gamma * v - omega0 * omega0 * x;
+
+        double xNext = x + dt * v;
+        double vNext = v + dt * acceleration;
+
+        return new double[] {xNext, vNext};
+    }
+
+    /** @return the natural (undamped) angular frequency (rad/s). */
+    public double getOmega0() {
+        return omega0;
+    }
+
+    /** @return the damping coefficient (s⁻¹). */
+    public double getGamma() {
+        return gamma;
+    }
+}