Refactor edmonds algorithm

[mjschwenne]

Hello!

I've finished my refactor of Edmond's optimal branching algorithm so it is not dependent on the Edmonds class or the MultiDiGraph_EdgeKey class. The algorithm itself now lives under maximum_branching and the other branching and arborescence functions transform the edge weights and use the maximum_branching function.

Things left to do

There are two things that still need to happen here.

1. I would like to deprecate the Edmonds class as well as MultiDiGraph_EdgeKey and the get_path function in branching.py. These classes (and function) are no longer required and always struck me as odd since the rest of the nx codebase doesn't use objects to run algorithms like this. However, I don't know how to deprecate anything in networkx and would appropriate some help getting that setup.
2. As mentioned in algorithms.tree.branchings breaks for all minimum_branching() calls #4836, the minimum_branching function will return an empty branching for graphs with only positive edge weights since it can choose to not add an edge which will move it further away from the minimum or maximum value. This isn't helpful, isn't documented and should be corrected. I can think of two ways to do this, either
   • Create a new function called minimal_branching which uses the same weight transformation as minimum_spanning_arborescence but doesn't throw an error when the result isn't an arborescence. This will let us return a branching which will be like an arborescence but doesn't have to span the whole graph and would be useful when the graph has multiple components.
   • Change the behavior of minimum_branching since it really isn't useful right now, although it would require some form of warning to the user that the behavior has changed. I'm not really sure if that's truly a deprecation or something less.

[dschult]

As for "how to do a deprecation", that sounds like something that would be a good section in the contributors guide. I'll try to put down what I understand to be the process here and use this PR as a guinea pig if you are willing.

Deprecating code:

• running the code should raise a DeprecationWarning with a message that says how to update the code to avoid the deprecation (if such a method exists) and which release the deprecated code will be removed. This process typically involves:
  • import warnings somewhere appropriate (at the top of the module or in the function if only one function
  • warnings.warn(msg, warnings.DeprecationWarning) but I think raise warnings.DeprecationWarning(msg) also works and I'm not sure which is preferred.
  • add a test that the warning occurs when calling that feature.
  • add the warnings filter to conftest.py in the function set_warnings (other examples are in that code).
  • add a couple lines to the deprecations section of doc/release/release_dev.py to show which PR, which function(s) and enough info to help a user looking for a solution. Look at previous release notes, e.g. release_2.8.rst for examples.
  • add a line to doc/developer/deprecations.rst to remind us to remove the code when the time comes to do that. The guidelines for picking a release to remove the code are in this file at the top.

Ask is anything isn't clear or doesn't work. :}

[dschult]

This looks good! :)
Thanks Matt!

[dschult]

Also, since this is a new function, can you please make the keyword arguments "keyword only" by adding a *, between the positional arguments and the keyword arguments?

[rossbar]

A couple minor suggestions but otherwise LGTM! I'm not too familiar with the Edmond's algorithm so (as always) I rely on the expertise of others :)

[rossbar]

LGTM, thanks @mjschwenne ! Just one last note about the summary in the new docstring, but other than that this is good to go.