feat(graph): add Push–Relabel max flow with tests and index

[SamXop123]

Add Push–Relabel (Relabel-to-Front variant) max-flow with tests and reference

Summary

• What: Introduces PushRelabel.maxFlow(int[][], int, int) to compute maximum flow on directed graphs using the Push–Relabel method. Adds robust tests and updates the index.
• Why: Complements existing max-flow algorithms (EdmondsKarp, Dinic), enabling parity checks and providing an alternative approach with strong practical performance.

Changes

• [new] src/main/java/com/thealgorithms/graph/PushRelabel.java
  • Array-based Push–Relabel with:
    • Preflow initialization.
    • discharge() pushing on admissible edges.
    • relabel() when no admissible edges.
    • Active vertex queue; enqueues neighbors when their excess becomes positive.
  • Returns excess[sink] as the max flow.
  • Javadoc includes Wikipedia reference.
• [new] src/test/java/com/thealgorithms/graph/PushRelabelTest.java
  • CLRS canonical network (expected flow 23).
  • Disconnected network (0).
  • source == sink (0).
  • Parity vs Dinic and EdmondsKarp on random small graphs.
• [updated] DIRECTORY.md
  • Added PushRelabel under graph/.

API

• PushRelabel.maxFlow(int[][] capacity, int source, int sink)
  • Input: square matrix capacity[u][v] >= 0, indices within [0, n).
  • Output: max-flow value as int.
  • Behavior: returns 0 when source == sink.

Algorithm details

• Method: Push–Relabel (array-based residual network).
• Key operations:
  • Preflow from source to neighbors; set height[source] = n.
  • While active vertex exists, discharge() pushes along admissible edges (height[u] == height[v] + 1); otherwise relabel(u).
  • When vertex v gains positive excess (and v is neither source nor sink), enqueue it.
• Complexity: Worst-case O(V^3) (array-based). Practical performance is good for moderate graphs.

Tests

• PushRelabelTest.clrsExample() verifies max flow 23 for classic network.
• PushRelabelTest.disconnectedGraph() verifies zero flow.
• PushRelabelTest.sourceEqualsSink() verifies zero flow.
• PushRelabelTest.parityWithOtherMaxFlow() asserts equality with Dinic and EdmondsKarp on random small graphs.

References

• Wikipedia: Push–Relabel maximum flow algorithm
  https://en.wikipedia.org/wiki/Push%E2%80%93relabel_maximum_flow_algorithm

Verification

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

Checklist

• I have read CONTRIBUTING.md.
• This pull request is all my own work.
• Filenames are in PascalCase.
• Functions and variable names follow Java naming conventions.
• New algorithm has a URL in comments (will add if maintainers request).
• Code formatted (clang-format) and mvn verify passes locally.

Issue linkage

• Fixes [FEATURE REQUEST] Add Push–Relabel (Relabel-to-Front variant) max-flow to graph package #6792

Notes for reviewers

• Implementation is matrix-based for consistency with Dinic and EdmondsKarp.
• If maintainers prefer an adjacency-list variant (with heuristics like global relabel or gap), happy to add in a follow-up.

Summary

Adds a complete, tested Push–Relabel max-flow implementation with documentation and references, consistent with existing APIs. Ready for review and merge.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 86.07595% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 77.81%. Comparing base (f8688ba) to head (fc68270).

Files with missing lines	Patch %	Lines
...main/java/com/thealgorithms/graph/PushRelabel.java	86.07%	5 Missing and 6 partials ⚠️

Additional details and impacted files

@@ Coverage Diff @@ ## master #6793 +/- ## ============================================ + Coverage 77.78% 77.81% +0.03%  - Complexity 6307 6331 +24  ============================================ Files 728 729 +1 Lines 21012 21091 +79 Branches 4097 4117 +20 ============================================ + Hits 16345 16413 +68  - Misses 4022 4027 +5  - Partials 645 651 +6 

☔ 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.

[alxkm]

Looks good. Thank you for the contribution.