Forward declaration. More...
#include <max_flow.h>
Public Types | |
| typedef Graph::NodeIndex | NodeIndex |
| typedef Graph::ArcIndex | ArcIndex |
| typedef Graph::OutgoingArcIterator | OutgoingArcIterator |
| typedef Graph::OutgoingOrOppositeIncomingArcIterator | OutgoingOrOppositeIncomingArcIterator |
| typedef Graph::IncomingArcIterator | IncomingArcIterator |
| typedef ZVector< ArcIndex > | ArcIndexArray |
| typedef NodeIndex | NodeHeight |
| The height of a node never excess 2 times the number of node, so we use the same type as a Node index. More... | |
| typedef ZVector< NodeHeight > | NodeHeightArray |
| enum | Status { NOT_SOLVED, OPTIMAL, INT_OVERFLOW, BAD_INPUT, BAD_RESULT } |
Public Member Functions | |
| GenericMaxFlow (const Graph *graph, NodeIndex source, NodeIndex sink) | |
| Initialize a MaxFlow instance on the given graph. More... | |
| virtual | ~GenericMaxFlow () |
| const Graph * | graph () const |
| Returns the graph associated to the current object. More... | |
| Status | status () const |
| Returns the status of last call to Solve(). More... | |
| NodeIndex | GetSourceNodeIndex () const |
| Returns the index of the node corresponding to the source of the network. More... | |
| NodeIndex | GetSinkNodeIndex () const |
| Returns the index of the node corresponding to the sink of the network. More... | |
| void | SetArcCapacity (ArcIndex arc, FlowQuantity new_capacity) |
| Sets the capacity for arc to new_capacity. More... | |
| void | SetArcFlow (ArcIndex arc, FlowQuantity new_flow) |
| Sets the flow for arc. More... | |
| bool | Solve () |
| Returns true if a maximum flow was solved. More... | |
| FlowQuantity | GetOptimalFlow () const |
| Returns the total flow found by the algorithm. More... | |
| FlowQuantity | Flow (ArcIndex arc) const |
| Returns the flow on arc using the equations given in the comment on residual_arc_capacity_. More... | |
| FlowQuantity | Capacity (ArcIndex arc) const |
| Returns the capacity of arc using the equations given in the comment on residual_arc_capacity_. More... | |
| void | GetSourceSideMinCut (std::vector< NodeIndex > *result) |
| Returns the nodes reachable from the source in the residual graph, the outgoing arcs of this set form a minimum cut. More... | |
| void | GetSinkSideMinCut (std::vector< NodeIndex > *result) |
| Returns the nodes that can reach the sink in the residual graph, the outgoing arcs of this set form a minimum cut. More... | |
| bool | CheckInputConsistency () const |
| Checks the consistency of the input, i.e. More... | |
| bool | CheckResult () const |
| Checks whether the result is valid, i.e. More... | |
| bool | AugmentingPathExists () const |
| Returns true if there exists a path from the source to the sink with remaining capacity. More... | |
| void | SetUseGlobalUpdate (bool value) |
| Sets the different algorithm options. More... | |
| void | SetUseTwoPhaseAlgorithm (bool value) |
| void | SetCheckInput (bool value) |
| void | SetCheckResult (bool value) |
| void | ProcessNodeByHeight (bool value) |
| FlowModel | CreateFlowModel () |
| Returns the protocol buffer representation of the current problem. More... | |
Protected Member Functions | |
| bool | IsAdmissible (ArcIndex arc) const |
| Returns true if arc is admissible. More... | |
| bool | IsActive (NodeIndex node) const |
| Returns true if node is active, i.e. More... | |
| void | SetCapacityAndClearFlow (ArcIndex arc, FlowQuantity capacity) |
| Sets the capacity of arc to 'capacity' and clears the flow on arc. More... | |
| bool | CheckRelabelPrecondition (NodeIndex node) const |
| Returns true if a precondition for Relabel is met, i.e. More... | |
| std::string | DebugString (const std::string &context, ArcIndex arc) const |
| Returns context concatenated with information about arc in a human-friendly way. More... | |
| void | InitializeActiveNodeContainer () |
| Initializes the container active_nodes_. More... | |
| NodeIndex | GetAndRemoveFirstActiveNode () |
| Get the first element from the active node container. More... | |
| void | PushActiveNode (const NodeIndex &node) |
| Push element to the active node container. More... | |
| bool | IsEmptyActiveNodeContainer () |
| Check the emptiness of the container. More... | |
| void | Refine () |
| Performs optimization step. More... | |
| void | RefineWithGlobalUpdate () |
| void | Discharge (NodeIndex node) |
| Discharges an active node node by saturating its admissible adjacent arcs, if any, and by relabelling it when it becomes inactive. More... | |
| void | InitializePreflow () |
| Initializes the preflow to a state that enables to run Refine. More... | |
| void | PushFlowExcessBackToSource () |
| Clears the flow excess at each node by pushing the flow back to the source: More... | |
| void | GlobalUpdate () |
| Computes the best possible node potential given the current flow using a reverse breadth-first search from the sink in the reverse residual graph. More... | |
| bool | SaturateOutgoingArcsFromSource () |
| Tries to saturate all the outgoing arcs from the source that can reach the sink. More... | |
| void | PushFlow (FlowQuantity flow, ArcIndex arc) |
| Pushes flow on arc, i.e. More... | |
| void | Relabel (NodeIndex node) |
| Relabels a node, i.e. More... | |
| NodeIndex | Head (ArcIndex arc) const |
| Handy member functions to make the code more compact. More... | |
| NodeIndex | Tail (ArcIndex arc) const |
| ArcIndex | Opposite (ArcIndex arc) const |
| bool | IsArcDirect (ArcIndex arc) const |
| bool | IsArcValid (ArcIndex arc) const |
| template<bool reverse> | |
| void | ComputeReachableNodes (NodeIndex start, std::vector< NodeIndex > *result) |
| Returns the set of nodes reachable from start in the residual graph or in the reverse residual graph (if reverse is true). More... | |
Protected Attributes | |
| const Graph * | graph_ |
| A pointer to the graph passed as argument. More... | |
| QuantityArray | node_excess_ |
| An array representing the excess for each node in graph_. More... | |
| NodeHeightArray | node_potential_ |
| An array representing the height function for each node in graph_. More... | |
| QuantityArray | residual_arc_capacity_ |
| An array representing the residual_capacity for each arc in graph_. More... | |
| ArcIndexArray | first_admissible_arc_ |
| An array representing the first admissible arc for each node in graph_. More... | |
| std::vector< NodeIndex > | active_nodes_ |
| A stack used for managing active nodes in the algorithm. More... | |
| PriorityQueueWithRestrictedPush< NodeIndex, NodeHeight > | active_node_by_height_ |
| A priority queue used for managing active nodes in the algorithm. More... | |
| NodeIndex | source_ |
| The index of the source node in graph_. More... | |
| NodeIndex | sink_ |
| The index of the sink node in graph_. More... | |
| Status | status_ |
| The status of the problem. More... | |
| std::vector< bool > | node_in_bfs_queue_ |
| BFS queue used by the GlobalUpdate() function. More... | |
| std::vector< NodeIndex > | bfs_queue_ |
| bool | use_global_update_ |
| Whether or not to use GlobalUpdate(). More... | |
| bool | use_two_phase_algorithm_ |
| Whether or not we use a two-phase algorithm: 1/ Only deal with nodes that can reach the sink. More... | |
| bool | process_node_by_height_ |
| Whether or not we use the PriorityQueueWithRestrictedPush to process the active nodes rather than a simple queue. More... | |
| bool | check_input_ |
| Whether or not we check the input, this is a small price to pay for robustness. More... | |
| bool | check_result_ |
| Whether or not we check the result. More... | |
| StatsGroup | stats_ |
| Statistics about this class. More... | |
Static Protected Attributes | |
| static const FlowQuantity | kMaxFlowQuantity |
| Maximum manageable flow. More... | |
Detailed Description
template<typename Graph>
class operations_research::GenericMaxFlow< Graph >
Forward declaration.
Generic MaxFlow (there is a default MaxFlow specialization defined below) that works with StarGraph and all the reverse arc graphs from graph.h, see the end of max_flow.cc for the exact types this class is compiled for.
Definition at line 144 of file max_flow.h.
Member Typedef Documentation
◆ ArcIndex
| typedef Graph::ArcIndex operations_research::GenericMaxFlow< Graph >::ArcIndex |
Definition at line 318 of file max_flow.h.
◆ ArcIndexArray
| typedef ZVector<ArcIndex> operations_research::GenericMaxFlow< Graph >::ArcIndexArray |
Definition at line 323 of file max_flow.h.
◆ IncomingArcIterator
| typedef Graph::IncomingArcIterator operations_research::GenericMaxFlow< Graph >::IncomingArcIterator |
Definition at line 322 of file max_flow.h.
◆ NodeHeight
| typedef NodeIndex operations_research::GenericMaxFlow< Graph >::NodeHeight |
The height of a node never excess 2 times the number of node, so we use the same type as a Node index.
Definition at line 327 of file max_flow.h.
◆ NodeHeightArray
| typedef ZVector<NodeHeight> operations_research::GenericMaxFlow< Graph >::NodeHeightArray |
Definition at line 328 of file max_flow.h.
◆ NodeIndex
| typedef Graph::NodeIndex operations_research::GenericMaxFlow< Graph >::NodeIndex |
Definition at line 317 of file max_flow.h.
◆ OutgoingArcIterator
| typedef Graph::OutgoingArcIterator operations_research::GenericMaxFlow< Graph >::OutgoingArcIterator |
Definition at line 319 of file max_flow.h.
◆ OutgoingOrOppositeIncomingArcIterator
| typedef Graph::OutgoingOrOppositeIncomingArcIterator operations_research::GenericMaxFlow< Graph >::OutgoingOrOppositeIncomingArcIterator |
Definition at line 321 of file max_flow.h.
Member Enumeration Documentation
◆ Status
|
inherited |
| Enumerator | |
|---|---|
| NOT_SOLVED | |
| OPTIMAL | |
| INT_OVERFLOW | |
| BAD_INPUT | |
| BAD_RESULT | |
Definition at line 302 of file max_flow.h.
Constructor & Destructor Documentation
◆ GenericMaxFlow()
| operations_research::GenericMaxFlow< Graph >::GenericMaxFlow | ( | const Graph * | graph, |
| NodeIndex | source, | ||
| NodeIndex | sink | ||
| ) |
Initialize a MaxFlow instance on the given graph.
The graph does not need to be fully built yet, but its capacity reservation are used to initialize the memory of this class. source and sink must also be valid node of graph.
◆ ~GenericMaxFlow()
|
inlinevirtual |
Definition at line 335 of file max_flow.h.
Member Function Documentation
◆ AugmentingPathExists()
| bool operations_research::GenericMaxFlow< Graph >::AugmentingPathExists | ( | ) | const |
Returns true if there exists a path from the source to the sink with remaining capacity.
This allows us to easily check at the end that the flow we computed is indeed optimal (provided that all the conditions tested by CheckResult() also hold).
◆ Capacity()
|
inline |
Returns the capacity of arc using the equations given in the comment on residual_arc_capacity_.
Definition at line 375 of file max_flow.h.
◆ CheckInputConsistency()
| bool operations_research::GenericMaxFlow< Graph >::CheckInputConsistency | ( | ) | const |
Checks the consistency of the input, i.e.
that capacities on the arcs are non-negative or null.
◆ CheckRelabelPrecondition()
|
protected |
Returns true if a precondition for Relabel is met, i.e.
the outgoing arcs of node are all either saturated or the heights of their heads are greater or equal to the height of node.
◆ CheckResult()
| bool operations_research::GenericMaxFlow< Graph >::CheckResult | ( | ) | const |
Checks whether the result is valid, i.e.
that node excesses are all equal to zero (we have a flow) and that residual capacities are all non-negative or zero.
◆ ComputeReachableNodes()
|
protected |
Returns the set of nodes reachable from start in the residual graph or in the reverse residual graph (if reverse is true).
◆ CreateFlowModel()
| FlowModel operations_research::GenericMaxFlow< Graph >::CreateFlowModel | ( | ) |
Returns the protocol buffer representation of the current problem.
◆ DebugString()
|
protected |
Returns context concatenated with information about arc in a human-friendly way.
◆ Discharge()
|
protected |
Discharges an active node node by saturating its admissible adjacent arcs, if any, and by relabelling it when it becomes inactive.
◆ Flow()
|
inline |
Returns the flow on arc using the equations given in the comment on residual_arc_capacity_.
Definition at line 365 of file max_flow.h.
◆ GetAndRemoveFirstActiveNode()
|
inlineprotected |
Get the first element from the active node container.
Definition at line 460 of file max_flow.h.
◆ GetOptimalFlow()
|
inline |
Returns the total flow found by the algorithm.
Definition at line 361 of file max_flow.h.
◆ GetSinkNodeIndex()
|
inline |
Returns the index of the node corresponding to the sink of the network.
Definition at line 349 of file max_flow.h.
◆ GetSinkSideMinCut()
| void operations_research::GenericMaxFlow< Graph >::GetSinkSideMinCut | ( | std::vector< NodeIndex > * | result | ) |
Returns the nodes that can reach the sink in the residual graph, the outgoing arcs of this set form a minimum cut.
Note that if this is the complement of GetNodeReachableFromSource(), then the min-cut is unique.
- Todo:
- (user): In the two-phases algorithm, we can get this minimum cut without doing the second phase. Add an option for this if there is a need to, note that the second phase is pretty fast so the gain will be small.
◆ GetSourceNodeIndex()
|
inline |
Returns the index of the node corresponding to the source of the network.
Definition at line 346 of file max_flow.h.
◆ GetSourceSideMinCut()
| void operations_research::GenericMaxFlow< Graph >::GetSourceSideMinCut | ( | std::vector< NodeIndex > * | result | ) |
Returns the nodes reachable from the source in the residual graph, the outgoing arcs of this set form a minimum cut.
◆ GlobalUpdate()
|
protected |
Computes the best possible node potential given the current flow using a reverse breadth-first search from the sink in the reverse residual graph.
This is an implementation of the global update heuristic mentioned in many max-flow papers. See for instance: B.V. Cherkassky, A.V. Goldberg, "On implementing push-relabel methods for the maximum flow problem", Algorithmica, 19:390-410, 1997. ftp://reports.stanford.edu/pub/cstr/reports/cs/tr/94/1523/CS-TR-94-1523.pdf
◆ graph()
|
inline |
Returns the graph associated to the current object.
Definition at line 338 of file max_flow.h.
◆ Head()
|
inlineprotected |
Handy member functions to make the code more compact.
Definition at line 532 of file max_flow.h.
◆ InitializeActiveNodeContainer()
|
protected |
Initializes the container active_nodes_.
◆ InitializePreflow()
|
protected |
Initializes the preflow to a state that enables to run Refine.
◆ IsActive()
|
inlineprotected |
Returns true if node is active, i.e.
if its excess is positive and it is neither the source or the sink of the graph.
Definition at line 437 of file max_flow.h.
◆ IsAdmissible()
|
inlineprotected |
Returns true if arc is admissible.
Definition at line 430 of file max_flow.h.
◆ IsArcDirect()
|
protected |
◆ IsArcValid()
|
protected |
◆ IsEmptyActiveNodeContainer()
|
inlineprotected |
Check the emptiness of the container.
Definition at line 477 of file max_flow.h.
◆ Opposite()
|
protected |
◆ ProcessNodeByHeight()
|
inline |
Definition at line 421 of file max_flow.h.
◆ PushActiveNode()
|
inlineprotected |
Push element to the active node container.
Definition at line 468 of file max_flow.h.
◆ PushFlow()
|
protected |
Pushes flow on arc, i.e.
consumes flow on residual_arc_capacity_[arc], and consumes -flow on residual_arc_capacity_[Opposite(arc)]. Updates node_excess_ at the tail and head of arc accordingly.
◆ PushFlowExcessBackToSource()
|
protected |
Clears the flow excess at each node by pushing the flow back to the source:
- Do a depth-first search from the source in the direct graph to cancel flow cycles.
- Then, return flow excess along the depth-first search tree (by pushing the flow in the reverse dfs topological order). The theoretical complexity is O(mn), but it is a lot faster in practice.
◆ Refine()
|
protected |
Performs optimization step.
◆ RefineWithGlobalUpdate()
|
protected |
◆ Relabel()
|
protected |
Relabels a node, i.e.
increases its height by the minimum necessary amount. This version of Relabel is relaxed in a way such that if an admissible arc exists at the current node height, then the node is not relabeled. This enables us to deal with wrong values of first_admissible_arc_[node] when updating it is too costly.
◆ SaturateOutgoingArcsFromSource()
|
protected |
Tries to saturate all the outgoing arcs from the source that can reach the sink.
Most of the time, we can do that in one go, except when more flow than kMaxFlowQuantity can be pushed out of the source in which case we have to be careful. Returns true if some flow was pushed.
◆ SetArcCapacity()
| void operations_research::GenericMaxFlow< Graph >::SetArcCapacity | ( | ArcIndex | arc, |
| FlowQuantity | new_capacity | ||
| ) |
Sets the capacity for arc to new_capacity.
◆ SetArcFlow()
| void operations_research::GenericMaxFlow< Graph >::SetArcFlow | ( | ArcIndex | arc, |
| FlowQuantity | new_flow | ||
| ) |
Sets the flow for arc.
◆ SetCapacityAndClearFlow()
|
inlineprotected |
Sets the capacity of arc to 'capacity' and clears the flow on arc.
Definition at line 442 of file max_flow.h.
◆ SetCheckInput()
|
inline |
Definition at line 419 of file max_flow.h.
◆ SetCheckResult()
|
inline |
Definition at line 420 of file max_flow.h.
◆ SetUseGlobalUpdate()
|
inline |
Sets the different algorithm options.
All default to true. See the corresponding variable declaration below for more details.
Definition at line 414 of file max_flow.h.
◆ SetUseTwoPhaseAlgorithm()
|
inline |
Definition at line 418 of file max_flow.h.
◆ Solve()
| bool operations_research::GenericMaxFlow< Graph >::Solve | ( | ) |
Returns true if a maximum flow was solved.
◆ status()
|
inline |
Returns the status of last call to Solve().
NOT_SOLVED is returned if Solve() has never been called or if the problem has been modified in such a way that the previous solution becomes invalid.
Definition at line 343 of file max_flow.h.
◆ Tail()
|
inlineprotected |
Definition at line 533 of file max_flow.h.
Member Data Documentation
◆ active_node_by_height_
|
protected |
A priority queue used for managing active nodes in the algorithm.
It allows to select the active node with highest height before each Discharge(). Moreover, since all pushes from this node will be to nodes with height greater or equal to the initial discharged node height minus one, the PriorityQueueWithRestrictedPush is a perfect fit.
Definition at line 597 of file max_flow.h.
◆ active_nodes_
|
protected |
A stack used for managing active nodes in the algorithm.
- Note
- the papers cited above recommend the use of a queue, but benchmarking so far has not proved it is better. In particular, processing nodes in LIFO order has better cache locality.
Definition at line 590 of file max_flow.h.
◆ bfs_queue_
|
protected |
Definition at line 611 of file max_flow.h.
◆ check_input_
|
protected |
Whether or not we check the input, this is a small price to pay for robustness.
Disable only if you know the input is valid because an invalid input can cause the algorithm to run into an infinite loop!
Definition at line 634 of file max_flow.h.
◆ check_result_
|
protected |
Whether or not we check the result.
- Todo:
- (user): Make the check more exhaustive by checking the optimality?
Definition at line 638 of file max_flow.h.
◆ first_admissible_arc_
|
protected |
An array representing the first admissible arc for each node in graph_.
Definition at line 584 of file max_flow.h.
◆ graph_
|
protected |
A pointer to the graph passed as argument.
Definition at line 547 of file max_flow.h.
◆ kMaxFlowQuantity
|
staticprotected |
Maximum manageable flow.
Definition at line 544 of file max_flow.h.
◆ node_excess_
|
protected |
An array representing the excess for each node in graph_.
Definition at line 550 of file max_flow.h.
◆ node_in_bfs_queue_
|
protected |
BFS queue used by the GlobalUpdate() function.
We do not use a C++ queue because we need access to the vector for different optimizations.
Definition at line 610 of file max_flow.h.
◆ node_potential_
|
protected |
An array representing the height function for each node in graph_.
For a given node, this is a lower bound on the shortest path length from this node to the sink in the residual network. The height of a node always goes up during the course of a Solve().
Since initially we saturate all the outgoing arcs of the source, we can never reach the sink from the source in the residual graph. Initially we set the height of the source to n (the number of node of the graph) and it never changes. If a node as an height >= n, then this node can't reach the sink and its height minus n is a lower bound on the shortest path length from this node to the source in the residual graph.
Definition at line 563 of file max_flow.h.
◆ process_node_by_height_
|
protected |
Whether or not we use the PriorityQueueWithRestrictedPush to process the active nodes rather than a simple queue.
This can only be true if use_global_update_ is true.
Note(user): using a template will be slightly faster, but since we test this in a non-critical path, this only has a minor impact.
Definition at line 629 of file max_flow.h.
◆ residual_arc_capacity_
|
protected |
An array representing the residual_capacity for each arc in graph_.
Residual capacities enable one to represent the capacity and flow for all arcs in the graph in the following manner. For all arc, residual_arc_capacity_[arc] = capacity[arc] - flow[arc] Moreover, for reverse arcs, capacity[arc] = 0 by definition, Also flow[Opposite(arc)] = -flow[arc] by definition. Therefore:
- for a direct arc: flow[arc] = 0 - flow[Opposite(arc)] = capacity[Opposite(arc)] - flow[Opposite(arc)] = residual_arc_capacity_[Opposite(arc)]
- for a reverse arc: flow[arc] = -residual_arc_capacity_[arc] Using these facts enables one to only maintain residual_arc_capacity_, instead of both capacity and flow, for each direct and indirect arc. This reduces the amount of memory for this information by a factor 2.
Definition at line 581 of file max_flow.h.
◆ sink_
|
protected |
The index of the sink node in graph_.
Definition at line 603 of file max_flow.h.
◆ source_
|
protected |
The index of the source node in graph_.
Definition at line 600 of file max_flow.h.
◆ stats_
|
mutableprotected |
Statistics about this class.
Definition at line 641 of file max_flow.h.
◆ status_
|
protected |
The status of the problem.
Definition at line 606 of file max_flow.h.
◆ use_global_update_
|
protected |
Whether or not to use GlobalUpdate().
Definition at line 614 of file max_flow.h.
◆ use_two_phase_algorithm_
|
protected |
Whether or not we use a two-phase algorithm: 1/ Only deal with nodes that can reach the sink.
At the end we know the value of the maximum flow and we have a min-cut. 2/ Call PushFlowExcessBackToSource() to obtain a max-flow. This is usually a lot faster than the first phase.
Definition at line 621 of file max_flow.h.
The documentation for this class was generated from the following file: