Add -Dinic’s Algorithm

[Erennn7]

PR: Dinic's Algorithm for Maximum Flow

This PR provides a comprehensive R implementation of Dinic's Algorithm, a highly efficient algorithm to compute the maximum flow in a flow network. The algorithm leverages level graphs and blocking flows to improve performance over classical methods like Ford-Fulkerson.

Overview

Dinic's Algorithm operates in two main phases iteratively:

1. Level Graph Construction (BFS):

   • Perform a Breadth-First Search from the source to label vertices with their distance from the source.
   • Only consider edges with remaining capacity.

2. Blocking Flow Computation (DFS):

   • Send flow along paths in the level graph using Depth-First Search.
   • Continue until no augmenting paths exist in the current level graph.

These steps are repeated until no augmenting path exists from the source to the sink. The approach ensures efficient convergence and allows multiple flows per BFS iteration.

Features

• Computes maximum flow in directed networks.
• Handles networks with multiple paths and varying capacities.
• Uses adjacency lists and capacity/flow matrices for efficiency.
• Finds the minimum cut automatically.
• Suitable for bipartite matching, multi-source/multi-sink networks, and assignment problems.
• Includes robust error handling and validation.

Complexity

• Time Complexity:
  • General graphs: O(V² * E)
  • Unit capacity networks: O(E * √V)
• Space Complexity: O(V + E) for adjacency lists, level arrays, and flow matrices.

Applications

• Network routing and traffic optimization
• Bipartite matching problems
• Image segmentation
• Airline scheduling and logistics
• Project selection and resource allocation

Demonstration

Example 1: Basic 6-Vertex Network

# Create network and add edges
network <- create_flow_network(6)
network <- add_edge(network, 1, 2, 16)
network <- add_edge(network, 1, 3, 13)
network <- add_edge(network, 2, 3, 10)
network <- add_edge(network, 2, 4, 12)
network <- add_edge(network, 3, 2, 4)
network <- add_edge(network, 3, 5, 14)
network <- add_edge(network, 4, 3, 9)
network <- add_edge(network, 4, 6, 20)
network <- add_edge(network, 5, 4, 7)
network <- add_edge(network, 5, 6, 4)

# Compute maximum flow
result <- dinic_max_flow(network, source = 1, sink = 6)
print_max_flow(result, network)
print_flow_edges(network)

[Copilot]

Pull Request Overview

This PR adds a comprehensive implementation of Dinic's Algorithm for computing maximum flow in directed networks. The algorithm uses level graphs (BFS) and blocking flows (DFS) to efficiently find the maximum flow from a source to a sink vertex, offering better performance than classical Ford-Fulkerson approaches.

Key changes:

• Complete Dinic's Algorithm implementation with BFS level graph construction and DFS blocking flow computation
• Support for flow network creation, edge addition, and flow visualization functions
• Four comprehensive examples demonstrating different use cases (basic networks, bipartite matching, multi-source/multi-sink)

[Erennn7]

@siriak please have a look

[Copilot]

Pull Request Overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.

[Copilot]

The function documentation uses an incorrect documentation format. R function documentation should use proper roxygen2 syntax with @param tags, not @param: with colons. The return value should be documented with @return without a colon. Similarly for other functions throughout the file.

[Copilot]

The file contains executable example code at the module level (lines 251-398). According to repository guidelines, examples should be included as commented code within the script, not as executable statements that run when the file is sourced. Consider commenting out or removing the executable examples or moving them to a separate example/demo file.