Implement DigraphIsKing and Digraph2Kings

doc/attr.xml

@@ -2399,3 +2399,29 @@ gap> Length(M);
   </Description>
 </ManSection>
 <#/GAPDoc>
+
+<#GAPDoc Label="Digraph2Kings">
+<ManSection>
+  <Oper Name="Digraph2Kings" Arg="D"/>
+  <Returns>A list.</Returns>
+  <Description>
+    If <A>D</A> is a tournament then this operation returns a list of the
+    2-kings in the tournament. If the tournament contains a source, then the
+    source is the only 2-king (see <Ref Attr="DigraphSources"/>). The number 
+    of 2-kings in a tournament without a source is at least three. A tournament
+    cannot have exactly two 2-kings.
+
+    <Example><![CDATA[
+gap> gr := Digraph([[2, 3, 4], [3, 5], [5], [2, 3], [1, 4]]);
+<immutable digraph with 5 vertices, 10 edges>
+gap> Digraph2Kings(gr);
+[ 1, 2, 5 ]
+gap> gr := Digraph([[2, 3, 4, 5], [3, 5], [5], [2, 3], [4]]);
+<immutable digraph with 5 vertices, 10 edges>
+gap> DigraphSources(gr);
+[ 1 ]
+gap> Digraph2Kings(gr);
+[ 1 ]]]></Example>
+  </Description>
+</ManSection>
+<#/GAPDoc>

doc/oper.xml

@@ -8,6 +8,37 @@
 #############################################################################
 ##
 
+<#GAPDoc Label="DigraphIsKing">
+<ManSection>
+  <Oper Name="DigraphIsKing" Arg="D, v, k"/>
+  <Returns><K>true</K> or <K>false</K>.</Returns>
+  <Description>
+    If <A>D</A> is a tournament and <A>v</A> is a vertex in the tournament,
+    then this operation returns <K>true</K> if every other vertex of <A>D</A>
+    is reachable from <A>v</A> by a path of length at most <A>k</A>. Else,
+    <K>false</K> is returned. <P/>
+
+    If <K>true</K> is returned, then the vertex, <A>v</A>, is a k-king. <P/>
+
+    <Example><![CDATA[
+gap> gr := Digraph([[2, 3, 4], [3, 5], [5], [2, 3], [1, 4]]);
+<immutable digraph with 5 vertices, 10 edges>
+gap> DigraphIsKing(gr, 2, 2);
+true
+gap> DigraphIsKing(gr, 3, 2);
+false
+gap> OutNeighboursOfVertex(gr, 3);
+[ 5 ]
+gap> OutNeighboursOfVertex(gr, 5);
+[ 1, 4 ]
+gap> Union(last, last2);
+[ 1, 4, 5 ]
+gap> DigraphIsKing(gr, 3, 4);
+true]]></Example>
+  </Description>
+</ManSection>
+<#/GAPDoc>
+
 <#GAPDoc Label="IsSubdigraph">
 <ManSection>
   <Oper Name="IsSubdigraph" Arg="super, sub"/>

doc/z-chap4.xml

@@ -75,6 +75,8 @@
     <#Include Label="HamiltonianPath">
     <#Include Label="NrSpanningTrees">
     <#Include Label="DigraphDijkstra">
+    <#Include Label="DigraphIsKing">
+    <#Include Label="Digraph2Kings">
   </Section>
 
   <Section><Heading>Cayley graphs of groups</Heading>

gap/attr.gd

@@ -45,6 +45,7 @@ DeclareAttribute("DigraphDegeneracy", IsDigraph);
 DeclareAttribute("DigraphDegeneracyOrdering", IsDigraph);
 DeclareAttribute("DIGRAPHS_Degeneracy", IsDigraph);
 DeclareAttribute("DigraphShortestDistances", IsDigraph);
+DeclareAttribute("Digraph2Kings", IsDigraph);
 DeclareAttribute("DigraphDiameter", IsDigraph);
 DeclareAttribute("DigraphGirth", IsDigraph);
 DeclareAttribute("DigraphOddGirth", IsDigraph);

gap/attr.gi

@@ -2609,3 +2609,15 @@ function(D)
   M := List(DigraphLoops(D), x -> [x, x]);
   return Union(M, DIGRAPHS_MateToMatching(D, mateD));
 end);
+
+InstallMethod(Digraph2Kings, "for a digraph", [IsDigraph],
+function(D)
+  local v, kings;
+  kings := [];
+  for v in DigraphVertices(D) do
+    if DigraphIsKing(D, v, 2) then
+      Add(kings, v);
+    fi;
+  od;
+  return kings;
+end);

gap/oper.gd

@@ -110,6 +110,8 @@ DeclareOperation("IsDigraphPath",
 DeclareOperation("IsDigraphPath", [IsDigraph, IsList]);
 
 # 9. Connectivity . . .
+DeclareOperation("DigraphIsKing", [IsDigraph, IsPosInt, IsPosInt]);
+
 DeclareOperation("DigraphFloydWarshall",
                  [IsDigraph, IsFunction, IsObject, IsObject]);
 DeclareOperation("DigraphDijkstra",

gap/oper.gi

@@ -1318,6 +1318,21 @@ end);
 # 9.  Connectivity
 #############################################################################
 
+InstallMethod(DigraphIsKing,
+"for a digraph and two positive integers",
+[IsDigraph, IsPosInt, IsPosInt],
+function(D, v, k)
+  local layers;
+  if not v in DigraphVertices(D) then
+    ErrorNoReturn("the 2nd argument <v> is not a vertex of the ",
+                  "1st argument <D>,");
+  elif not IsTournament(D) then
+    ErrorNoReturn("the 1st argument <D> must be a tournament,");
+  fi;
+  layers := DigraphLayers(D, v);
+  return ((Length(layers) <= k + 1) and (Union(layers) = DigraphVertices(D)));
+end);
+
 InstallMethod(DigraphFloydWarshall,
 "for a digraph by out-neighbours, function, object, and object",
 [IsDigraphByOutNeighboursRep, IsFunction, IsObject, IsObject],

tst/standard/attr.tst

@@ -14,6 +14,22 @@ gap> LoadPackage("digraphs", false);;
 #
 gap> DIGRAPHS_StartTest();
 
+# Digraph2Kings: for a digraph
+gap> gr := Digraph([[2], [3, 4], [1, 4], [1]]);
+<immutable digraph with 4 vertices, 6 edges>
+gap> Digraph2Kings(gr);
+[ 1, 2, 3 ]
+gap> gr := Digraph([[], [3, 4], [1, 4], [1]]);
+<immutable digraph with 4 vertices, 5 edges>
+gap> Digraph2Kings(gr);
+Error, the 1st argument <D> must be a tournament,
+gap> gr := RandomTournament(10);
+<immutable tournament with 10 vertices>
+gap> Length(Digraph2Kings(gr)) >= 1;
+true
+gap> Length(Digraph2Kings(gr)) <> 2;
+true
+
 #  DigraphSource and DigraphRange
 gap> nbs := [[12, 22, 17, 1, 10, 11], [23, 21, 21, 16],
 >  [15, 5, 22, 11, 12, 8, 10, 1], [21, 15, 23, 5, 23, 8, 24],

tst/standard/oper.tst

@@ -14,6 +14,24 @@ gap> LoadPackage("digraphs", false);;
 #
 gap> DIGRAPHS_StartTest();
 
+#  DigraphIsKing: for a digraph, a node and a positive integer
+gap> gr := Digraph([[2], [3, 4], [1, 4], [1]]);
+<immutable digraph with 4 vertices, 6 edges>
+gap> IsTournament(gr);
+true
+gap> DigraphIsKing(gr, 2, 2);
+true
+gap> DigraphIsKing(gr, 4, 2);
+false
+gap> DigraphIsKing(gr, 4, 3);
+true
+gap> DigraphIsKing(gr, 5, 2);
+Error, the 2nd argument <v> is not a vertex of the 1st argument <D>,
+gap> gr := Digraph([[], [3, 4], [1, 4], [1]]);
+<immutable digraph with 4 vertices, 5 edges>
+gap> DigraphIsKing(gr, 2, 2);
+Error, the 1st argument <D> must be a tournament,
+
 #  DigraphRemoveLoops
 gap> gr := DigraphFromDigraph6String("&EhxPC?@");
 <immutable digraph with 6 vertices, 11 edges>