Added explanations for each Algorithm and edited gapdocs + tests for implemented methods

Author: rm387

doc/oper.xml

@@ -1954,6 +1954,46 @@ rec( idom := [ 2, fail, 2, 2, 2 ], preorder := [ 2, 1, 3, 4, 5 ] )
 </ManSection>
 <#/GAPDoc>
 
+<#GAPDoc Label="DigraphDominatingSet">
+<ManSection>
+  <Oper Name="DigraphDominatingSet" Arg="digraph"/>
+  <Returns>A List</Returns>
+  <Description>
+      This creates a dominating set of <A>digraph</A>, which is a subset of the vertices in 
+      <A>digraph</A> such that the neighbourhood of this subset of vertices is equal to all 
+      the vertices in <A>digraph</A>. </P>
+
+      The domating set returned will be one of potentially multiple possible dominating sets for the digraph.
+  <Example><![CDATA[
+D := Digraph([[2,3,4], [],[],[]]);;
+gap> DigraphDominatingSet(D);
+[ 4, 1 ]
+gap> DigraphDominatingSet(D);
+[ 1 ]]]></Example>
+  </Description>
+</ManSection>
+<#/GAPDoc>
+
+<#GAPDoc Label="DigraphGetNeighbourhood">
+<ManSection>
+  <Oper Name="DigraphGetNeighbourhood" Arg="digraph, vertices"/>
+  <Returns>A List</Returns>
+  <Description>
+    This returns the set of vertices that are adjacent to a vertex in <A>vertices</A>,
+    not including any vertices that exist in <A>vertices</A>. 
+  <Example><![CDATA[
+gap> D := Digraph([[2, 3, 4], [1], [], []]);;
+gap> DigraphGetNeighbourhood(D, [1]);
+[ 2, 3, 4 ]
+gap> DigraphGetNeighbourhood(D, [1, 2]);
+[ 3, 4 ]
+gap> D := Digraph([[2, 3, 4], [], [], []]);;
+gap> DigraphGetNeighbourhood(D, [2]);
+[  ]]]></Example>
+  </Description>
+</ManSection>
+<#/GAPDoc>
+
 <#GAPDoc Label="PartialOrderDigraphMeetOfVertices">
 <ManSection>
   <Oper Name="PartialOrderDigraphMeetOfVertices"

doc/weights.xml

@@ -272,6 +272,31 @@ gap> Sum(flow[1]);
 </ManSection>
 <#/GAPDoc>
 
+<#GAPDoc Label="DigraphEdgeConnectivity">
+<ManSection>
+  <Attr Name="DigraphEdgeConnectivity" Arg="digraph"/>
+  <Returns>An integer</Returns>
+  <Description>
+    This returns a record representing the edge connectivity of <A>digraph</A>.<P/>
+
+    It makes use of  <C>DigraphMaximumFlow(<A>digraph</A>)</C>, by constructing an edge-weighted Digraph
+    with edge weights of 1, then using the Max-flow min-cut theorem to determine the size of the minimum cut.
+    For a digraph, the minimum cut is the set of edges that need to be removed to ensure the digraph is 
+    no longer Strongly Connected. </P>
+    <Example><![CDATA[
+gap> D := Digraph([[2, 3, 4], [1, 3, 4], [1, 2], [2, 3]]);;
+gap> DigraphEdgeConnectivity(D);
+2
+gap> D := Digraph([[], [1, 2], [2]]);;
+gap> DigraphEdgeConnectivity(D);
+0
+gap> D := Digraph([[1, 2, 3, 4, 5], [1, 2, 3, 4, 5], [1, 2, 3, 4, 5], [1, 2, 3, 4, 5], [1, 2, 3, 4, 5]]);;
+gap> DigraphEdgeConnectivity(D);
+4]]></Example>
+  </Description>
+</ManSection>
+<#/GAPDoc>
+
 <#GAPDoc Label="RandomUniqueEdgeWeightedDigraph">
 <ManSection>
   <Oper Name="RandomUniqueEdgeWeightedDigraph" Arg="[filt, ]n[, p]"/>

gap/oper.gi

@@ -2523,6 +2523,8 @@ function(D, root)
 end);
 
 # For calculating a dominating set for a digraph
+# Algorithm 7 in :
+# https://www.cse.msu.edu/~cse835/Papers/Graph_connectivity_revised.pdf
 InstallMethod(DigraphDominatingSet, "for a digraph",
 [IsDigraph],
 function(digraph)

gap/weights.gi

@@ -772,7 +772,27 @@ function(D, start, destination)
   return flows;
 end);
 
-# DigraphEdgeConnectivity calculated using Spanning Trees
+#############################################################################
+# Digraph Edge Connectivity
+#############################################################################
+
+# Algorithms constructed off the algorithms detailed in:
+# https://www.cse.msu.edu/~cse835/Papers/Graph_connectivity_revised.pdf
+# Each Algorithm uses a different method to decrease the time complexity,
+# of calculating Edge Connectivity, though all make use of DigraphMaximumFlow()
+# due to the Max-Flow, Min-Cut Theorem
+
+# Algorithm 1: Calculating the Maximum Flow of every possible source and sink
+# Algorithm 2: Calculating the Maximum Flow to all sinks of an arbitrary source
+# Algorithm 3: Finding Maximum Flow within the non-leaves of a Spanning Tree
+# Algorithm 4: Constructing a spanning tree with a high number of leaves
+# Algorithm 5: Using the spanning tree^ to find Maximum Flow within non-leaves
+# Algorithm 6: Finding Maximum Flow within a dominating set of the digraph
+# Algorithm 7: Constructing a dominating set for use in Algorithm 6
+
+# Algorithms 4-7 are used below:
+
+# DigraphEdgeConnectivity calculated using Spanning Trees (Algorithm 4 & 5)
 InstallMethod(DigraphEdgeConnectivity, "for a digraph",
 [IsDigraph],
 function(digraph)
@@ -816,7 +836,6 @@ function(digraph)
     Append(added, Difference(OutNeighbours(EdgeD)[v], added));
 
     # Select the neighbour to v with the highest number of not-added neighbours:
-
     notadded := Difference(VerticesED, added);
     max := 0;
     NextVertex := v;
@@ -839,17 +858,15 @@ function(digraph)
 
   od;
 
-  # Algorithm 5: Using Algorithm 4 to find the Edge Connectivity
-
+  # Algorithm 5: Iterating through the non-leaves of the
+  # Spanning Tree created in Algorithm 4 to find the Edge Connectivity
   non_leaf := [];
   for b in VerticesED do
     if not IsEmpty(OutNeighbours(st)[b]) then
       Append(non_leaf, [b]);
     fi;
   od;
 
-  # Get the smaller of non_leaf and Difference(Vertices in EdgeD, non_leaf)
-
   if (Length(non_leaf) > 1) then
     u := non_leaf[1];
 
@@ -872,6 +889,7 @@ function(digraph)
   else
     # In the case of spanning trees with only one non-leaf node,
     # the above algorithm does not work
+    # Revert to iterating through all vertices of the original digraph
 
     u := 1;
     for v in [2 .. DigraphNrVertices(EdgeD)] do
@@ -897,7 +915,7 @@ function(digraph)
   return min;
 end);
 
-# Digraph EdgeConnectivity calculated with Dominating Sets
+# Digraph EdgeConnectivity calculated with Dominating Sets (Algorithm 6-7)
 InstallMethod(DigraphEdgeConnectivityDS, "for a digraph",
 [IsDigraph],
 function(digraph)
@@ -923,10 +941,10 @@ function(digraph)
   min := -1;
 
   # Algorithm 7: Creating a dominating set of the digraph
-
+  
   D := DigraphDominatingSet(digraph);
 
-  # Algorithm 6:
+  # Algorithm 6: Using the dominating set created to determine the Maximum Flow
 
   if Length(D) > 1 then
 
@@ -945,6 +963,7 @@ function(digraph)
   else
     # If the dominating set of EdgeD is of Length 1,
     # the above algorithm will not work
+    # Revert to iterating through all vertices of the original digraph
 
     u := 1;
 

tst/standard/oper.tst

@@ -2861,6 +2861,21 @@ rec( idom := [ fail ], preorder := [ 1 ] )
 gap> DominatorTree(D, 6);
 rec( idom := [ ,,,,, fail ], preorder := [ 6 ] )
 
+# DigraphGetNeighbourhood
+gap> D := Digraph([[2, 3, 4], [1], [], []]);;
+gap> DigraphGetNeighbourhood(D, [1]);
+[ 2, 3, 4 ]
+gap> DigraphGetNeighbourhood(D, [1, 2]);
+[ 3, 4 ]
+gap> D := Digraph([[2, 3, 4], [], [], []]);;
+gap> DigraphGetNeighbourhood(D, [2]);
+[  ]
+gap> D := Digraph([[2], [3], [4], [1]]);;
+gap> DigraphGetNeighbourhood(D, [1]);
+[ 2 ]
+gap> DigraphGetNeighbourhood(D, [1, 3]);
+[ 2, 4 ]
+
 # IsDigraphPath
 gap> D := Digraph(IsMutableDigraph, Combinations([1 .. 5]), IsSubset);
 <mutable digraph with 32 vertices, 243 edges>

tst/standard/weights.tst

@@ -368,6 +368,20 @@ gap> gr := EdgeWeightedDigraph([[2], [3, 6], [4], [1, 6], [1, 3], []],
 gap> DigraphMaximumFlow(gr, 5, 6);
 [ [ 10 ], [ 3, 7 ], [ 7 ], [ 0, 7 ], [ 10, 4 ], [  ] ]
 
+# EdgeConnectivity
+gap> d := Digraph([[2, 3], [2, 3], [1, 2, 3]]);;
+gap> DigraphEdgeConnectivity(d);
+1
+gap> D := RandomDigraph(1);;
+gap> DigraphEdgeConnectivity(D);
+0
+gap> d := Digraph([[2, 4], [3], [1, 5], [3], [4]]);;
+gap> DigraphEdgeConnectivity(d);
+1
+gap> D := Digraph([[1, 2, 3, 4, 5], [1, 2, 3, 4, 5], [1, 2, 3, 4, 5], [1, 2, 3, 4, 5], [1, 2, 3, 4, 5]]);;
+gap> DigraphEdgeConnectivity(D);
+4
+
 #############################################################################
 # 6. Random edge-weighted digraphs
 #############################################################################

tst/testinstall.tst

@@ -554,21 +554,12 @@ gap> OutNeighbours(C);
 gap> D := Digraph([[2, 3, 4], [1, 3, 4], [1, 2], [2, 3]]);;
 gap> DigraphEdgeConnectivity(D);
 2
-gap> C := Digraph([[2, 3], [2, 3], [1, 2, 3]]);;
-gap> DigraphEdgeConnectivity(C);
-1
 gap> D := Digraph([[], [1, 2], [2]]);;
 gap> DigraphEdgeConnectivity(D);
 0
 gap> C := Digraph([[3, 4], [1, 3, 4], [2], [3]]);;
 gap> DigraphEdgeConnectivity(C);
 1
-gap> D := RandomDigraph(1);;
-gap> DigraphEdgeConnectivity(D);
-0
-gap> C := Digraph([[2, 4], [3], [1, 5], [3], [4]]);;
-gap> DigraphEdgeConnectivity(C);
-1
 gap> D := Digraph([[ 1, 2, 3, 4, 5 ], [ 1, 2, 3, 4, 5 ], [ 1, 2, 3, 4, 5 ], [ 1, 2, 3, 4, 5 ], [ 1, 2, 3, 4, 5 ]]);;
 gap> DigraphEdgeConnectivity(D);
 4