Merge remote-tracking branch 'upstream/master'
Merge remote-tracking branch 'upstream/master'
Add Goldberg-Radzik shortest path algorithm
Fix python2.6 compatibility in goldberg_radzik
Fix python2.6 compatibility in goldberg_radzik
Improve efficiency of goldberg_radzik
Add Edmonds-Karp maxflow algorithm
Refactor flow package.

This refactoring follows from the discussion at #1096 and #1095. It is fully backwards compatible. The main changes are:

1. Rename max_flow and min_cut to maximum_flow and minimum_cut to be consistent with NetworkX naming convention. The short names can still be used (eg nx.max_flow(...)) but are not in the documentation.

2. maximum_flow and minimum_cut accept a new parameter flow_func for the function that will perform the computation. A default_flow_func is set, which is preflow_push_value, based on the benckmarks by @ysitu at #1099.

3. The legacy implementation of ford_fulkerson and firends is separated in its own file and refactored for it to follow the new conventions in the function names, the implementation is the same.

4. Added a new function that return the residual network for each algorithm implementation. Also added docstrings explaining the conventions used in the residual network.

4. Refactored tests. Now it is easy to add a new maximum flow algorithm for testing. They take maybe a bit too long, but now we test all flow related functions.

5. The functions <algo_name>_{value|flow|residual} are not imported to NetworkX base namespace, it is necessary now to explicitly import them from networkx.algorithms.flow, the exception is ford_fulkerson_flow for backwards compatibility.

6. The maximum flow related functions imported in networkx namespace are: maximum_flow, minimum_cut, ford_fulkerson, preflow_push, shortest_augmenting_path. For convenience max_flow and min_cut are also imported. And for backwards compatibility: ford_fulkerson_flow and ford_fulkerson_flow_and_auxiliary.
Reduce constant factor of maxflow algorithms
Reduce constant factor of maxflow algorithms (cont'd)
Reduce constant factor of maxflow algorithms (cont'd)
Add edmonds_karp_residual function, and edmonds_karp* to tests.
Expose compute_flow parameter in preflow_push_residual.

Also fixed a rendering issue in its docsting.
Improve preflow_push_residual docstring.
More docstring fixes.
Add msg parameter to assert_* for keeping track of which function fails.

This does not work for assert_raises, thus we cannot keep track of which flow function fails in assert_raises maximum flow tests.
Keep refactoring. Implementation of ysitu's proposal in #1102.

This implements most of ysitu's proposal (see #1102) on the inetrfaces of flow algorithms. It is still backwards compatible. The main changes are:

1. Removed all {residual|value|flow} functions for the new algorithms. Each algorithm exposes only a function named `algorithm_name` that returns the residual network after computing the maximum flow. Internally we use residual networks everywhere. This simplifies code and tests.

2. Added a new parameter `legacy` to `ford_fulkerson` (default True). If it's True it returns a tuple (flow_value, flow_dict) as it used to do. If `legacy` is False then it returns the residual network, with the flow_value and the flow_dict as graph attributes. Thus we can use it internally (tests, other functions) in more or less the same way that we use the new algorithms. Expanded docstrings explaining all this. The functions `ford_fulkerson_value` and `ford_fulkerson_residual` introduced in the first refactoring are removed. The functions `ford_fulkerson_flow` and `ford_fulkerson_flow_and_auxiliary` are kept here for backwards compatibility, but I'll remove them in a separated commit.

3. I named the parameter `value_only` (ysitu proposed `min_cut_only`) and changed a bit the semantics. It defines what the functions `maximum_flow` and `minimum_cut` return. If True they return the maximum flow value, otherwise they return the actual flow or the set of edges that form the minimum cut. All algorithms recognize this parameter, for the ones in which it's not applicable they just ignore it.

4. The `maximum_flow` and `minimum_cut` functions deal now with `ford_fulkerson` as especial case. They also accept `**kwargs` and pass them to the function implementing the computation. This still needs work and do some checks on the sanity of the arguments passed to flow algorothms.

5. We import everything again from the flow package, without the {residual|value|flow} functions there is no need to keep stuff only to the flow package.

6. I've just adapted the old tests, more tests needed for testing the interface and new features of maximum_flow and minimum_cut. Now tests take less time because we are not testing redundant {residual|value|flow} functions.

7. `max_flow` and `min_cut` are alias for `maximum_flow` and `minimum_cut`. I think it's not a good idea to have them behave different, it could be a source of confusion.
Improve maximum flow and minimum cut tests.

Added a validate_cut function that also validates the minimum cut, also added a class for testing the interface to maximum_flow and minimum_cut, we should add more tests here. Moved the tests especific to one algorithm outside the class for common tests.
Return the node patrition instead of the cut set in minimum_cut.

Also added how to compute the cut set in the documentation. Some other fixes in the docstrings.
Added See Also section in the docstrings of max flow algorithms.