feat: Add Hungarian Algorithm (Assignment Problem) with tests and reference [GRAPHS]

[SamXop123]

Title

Add Hungarian Algorithm (Kuhn–Munkres) for the Assignment Problem with tests and reference

Summary

• What: Implements the Hungarian Algorithm (Kuhn–Munkres) to solve the minimum-cost assignment problem on non-negative rectangular cost matrices.
• Why: Complements graph/ with a classic O(n^3) assignment solver frequently used in scheduling/matching. Aligns with existing matching/flow tools.

Changes

• [new] src/main/java/com/thealgorithms/graph/HungarianAlgorithm.java

  • Pads rectangular matrices to square internally.
  • Returns Result { int[] assignment, int minCost } where assignment[i] is the chosen column for row i, or -1 if the row is unassigned when rows > cols.
  • Validates input (non-null, rectangular, non-negative entries).
  • Javadoc includes description, constraints, complexity, and Wikipedia reference.

• [new] src/test/java/com/thealgorithms/graph/HungarianAlgorithmTest.java

  • classicSquareExample: 3×3 canonical matrix, expects assignment [1,0,2] and cost 5.
  • rectangularMoreRows: 3×2 matrix, two assignments and one -1; minimal cost 3.
  • zeroDiagonal: zero diagonal 3×3 → minimal cost 0.

• [updated] DIRECTORY.md

  • Added HungarianAlgorithm under graph/, alphabetically.

API

• Class: com.thealgorithms.graph.HungarianAlgorithm
• Method: public static HungarianAlgorithm.Result solve(int[][] cost)
• Result:
  • int[] assignment — column chosen for each row (or -1 if unassigned in rectangular case).
  • int minCost — total minimal cost across assigned pairs.

Complexity

• Time: O(n^3), where n = max(rows, cols)
• Space: O(n^2) for padded matrix and bookkeeping arrays

Validation and Constraints

• Input matrix is non-null, rectangular (equal-length rows), and all entries are ≥ 0.
• Rectangular matrices are supported; unassigned rows remain -1 in the result.

Tests

• HungarianAlgorithmTest validates:
  • Correctness on a known 3×3 case.
  • Rectangular behavior with minimal total cost and proper unassigned rows.
  • Trivial zero-diagonal case yields zero cost.

References

• Wikipedia: https://en.wikipedia.org/wiki/Hungarian_algorithm

Verification

• mvn verify passes locally (unit tests + Checkstyle + PMD + SpotBugs).
• Code formatted via clang-format with project style.

Issue Linkage

• Fixes [FEATURE REQUEST] Hungarian Algorithm (Kuhn–Munkres) for the Assignment Problem [Graphs] #6806

Checklist

• I have read CONTRIBUTING.md.
• This pull request is all my own work -- I have not plagiarized it.
• All filenames are in PascalCase.
• All functions and variable names follow Java naming conventions.
• All new algorithms have a URL in their comments that points to Wikipedia or other similar explanations.
• All new code is formatted with clang-format -i --style=file path/to/your/file.java

Notes for Reviewers

• The current implementation uses int costs for consistency with existing graph algorithms. If desired, we can extend to long in a follow-up.
• The result format is row-centric; a column-centric mapping can be added later if helpful.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 82.19178% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 77.83%. Comparing base (3519a91) to head (6b8a959).

Files with missing lines	Patch %	Lines
...va/com/thealgorithms/graph/HungarianAlgorithm.java	82.19%	5 Missing and 8 partials ⚠️

Additional details and impacted files

@@            Coverage Diff            @@
##             master    #6807   +/-   ##
=========================================
  Coverage     77.83%   77.83%           
- Complexity     6332     6350   +18     
=========================================
  Files           729      730    +1     
  Lines         21091    21164   +73     
  Branches       4117     4139   +22     
=========================================
+ Hits          16416    16474   +58     
- Misses         4026     4032    +6     
- Partials        649      658    +9     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.