Added DigraphMinimumCutSet

[frankiegillis]

This adds the function DigraphMinimumCutSet using the DigraphMaximumFlow method and the max-flow min-cut theorem. See issue #867.

[reiniscirpons]

Thanks for the contribution, looks solid, some suggestions for docs and performance above, mostly minor.

In addition to the comments above, it looks like doc for the function is not linked in the manual, you should add

    <#Include Label="DigraphMinimumCut">

to z-chap5.xml in the appropriate location to get your documentation to show up in the manual (you can test this by seeing if ?DigraphMinimumCut finds the doc inside of gap).

I would also suggest changing the name of the function to DigraphMinimumCut since what its computing is the cut not the cut-set (see the definitions in https://en.wikipedia.org/wiki/Max-flow_min-cut_theorem#Cuts). It might also be good to implement a separate DigraphMinimumCutSet which wraps your current function and computes the edges.

[reiniscirpons]

The name of the documentation function does not match the implementation. For what its worth I think this function should be called DigraphMinimumCut, since we are computing the cut (the set of vertices in one part of the cut) instead of the cut set (the set of edges separating both parts of the cut)

[reiniscirpons]

Same comment about name matching doc as above

[reiniscirpons]

Suggested change

	An <E>s-t cut set</E> is a partition of the vertices [S, T] such that s is in S and
	An <E><M>s</M>-<M>t</M> cut</E> is a partition of the vertices <M>\{S, T\}</M> such that <A>s</A> is in <M>S</M> and

Same comment about before. Try applying markup as you would in e.g. latex to separate maths from text more. Propagate to rest of doc.

Also personal preference but I like curly braces for sets better, exercise your better judgement.

[reiniscirpons]

Suggested change

	<A>t</A>, this returns a list of two lists representing the components of
	a minimal s-t cut set of <A>digraph</A>. <P/>
	<A>t</A>, this function returns a list of two lists representing the components of
	the minimum <M>s</M>-<M>t</M> cut of <A>digraph</A>. <P/>

Changes to wording to match what the function does better, also I think we should use wrap the s-t is math markup.

[reiniscirpons]

Suggested change

	DeclareOperation("DigraphMinimumCutSet",
	DeclareOperation("DigraphMinimumCut",

I suggest renaming the function because of the cut and cut-set distinction mentioned above.

Might be useful to implement another function DigraphMinimumCutSet which computes the set of edges separating the two parts of the partition too? Its likely just a simple wrapper around your DigraphMinimumCut function.

[reiniscirpons]

Suggested change

	InstallMethod(DigraphMinimumCutSet, "for an edge weighted digraph",
	InstallMethod(DigraphMinimumCut, "for an edge weighted digraph",

Same comment as above.

[reiniscirpons]

Minor optimization: Because digraphs must be homogenous (all vertices are in the range [1 .. DigraphNrVertices(D)] with no holes), it might be better performance to check if s >= 1 and s <= DigraphNrVertices(D).

[reiniscirpons]

The IsReachable function performs a BFS for each call to it, however I think you could compute all the vertices in set S by a single BFS if you implement itself. This would provide a factor of $n$ speedup and would also mean you could avoid computing the residual capacity digraph G above (since you could just check if the flow is less than the weight as you are doing the BFS).