oper: add IsDigraphPath

Author: james-d-mitchell

doc/oper.xml

@@ -1382,7 +1382,9 @@ gap> VerticesReachableFrom(D, 5);
 
     The method for <C>DigraphPath</C> has worst case complexity of <M>O(m +
       n)</M> where <M>m</M> is the number of edges and <M>n</M> the number of
-    vertices in <A>digraph</A>.
+      vertices in <A>digraph</A>.<P/>
+
+      See also <Ref Oper="IsDigraphPath"/>.
 
 <Example><![CDATA[
 gap> D := Digraph([[2], [3], [2, 3]]);
@@ -2131,3 +2133,55 @@ gap> data;
 </Description>
 </ManSection>
 <#/GAPDoc>
+
+<#GAPDoc Label="IsDigraphPath">
+<ManSection>
+  <Oper Name="IsDigraphPath" Arg="D, v, a"/>
+  <Oper Name="IsDigraphPath" Arg="D, list" Label="for a digraph and list"/>
+  <Returns><K>true</K> or <K>false</K>.</Returns>
+  <Description>
+    This function returns <K>true</K> if the arguments <A>v</A> and <A>a </A>
+    describe a path in the digraph <A>D</A>.
+
+    A directed path (or directed cycle) of non-zero length <C>n-1</C>,
+    <M>(v_1, e_1, v_2, e_2, ..., e_{n-1}, v_n)</M>,
+    is represented by a pair of lists <C>[<A>v</A>, <A>a</A>]</C> as follows:
+
+    <List>
+      <Item>
+        <A>v</A> is the list <M>[v_1, v_2, ..., v_n]</M>.
+      </Item>
+      <Item>
+        <A>a</A> is the list of positive integers <M>[a_1, a_2, ..., a_{n-1}]</M>
+        where for each each <M>i &lt; n</M>, <M>a_i</M> is the position of
+        <M>v_{i+1}</M> in
+        <C>OutNeighboursOfVertex(</C><A>D</A><C>,</C><M>v_i</M><C>)</C>
+        corresponding to the edge <M>e_i</M>.  This can be useful if the
+        position of a vertex in a list of out-neighours is significant, for
+        example in orbit digraphs.
+      </Item>
+    </List>
+
+    If the arguments to <C>IsDigraphPath</C> are a digraph <A>D</A> and list
+    <A>list</A>, then this is equivalent to calling <C>IsDigraphPath(<A>D</A>,
+    <A>list</A>[1], <A>list</A>[2])</C>.
+
+    <Example><![CDATA[
+gap> D := Digraph(IsMutableDigraph, Combinations([1 .. 5]), IsSubset);
+<mutable digraph with 32 vertices, 243 edges>
+gap> DigraphReflexiveTransitiveReduction(D);
+<mutable digraph with 32 vertices, 80 edges>
+gap> MakeImmutable(D);
+<immutable digraph with 32 vertices, 80 edges>
+gap> IsDigraphPath(D, [32, 31, 33], [1, 1]);
+false
+gap> IsDigraphPath(D, [1], []);
+true
+gap> IsDigraphPath(D, [6, 9, 16, 17], [3, 3, 2]);
+true
+gap> IsDigraphPath(D, DigraphPath(D, 6, 1));
+true
+]]></Example>
+  </Description>
+</ManSection>
+<#/GAPDoc>

doc/z-chap4.xml

@@ -63,6 +63,7 @@
     <#Include Label="DigraphPeriod">
     <#Include Label="DigraphFloydWarshall">
     <#Include Label="IsReachable">
+    <#Include Label="IsDigraphPath">
     <#Include Label="VerticesReachableFrom">
     <#Include Label="DigraphPath">
     <#Include Label="DigraphShortestPath">

gap/oper.gd

@@ -92,6 +92,9 @@ DeclareOperation("IsMatching", [IsDigraph, IsHomogeneousList]);
 DeclareOperation("IsMaximalMatching", [IsDigraph, IsHomogeneousList]);
 DeclareOperation("IsMaximumMatching", [IsDigraph, IsHomogeneousList]);
 DeclareOperation("IsPerfectMatching", [IsDigraph, IsHomogeneousList]);
+DeclareOperation("IsDigraphPath",
+                 [IsDigraph, IsHomogeneousList, IsHomogeneousList]);
+DeclareOperation("IsDigraphPath", [IsDigraph, IsList]);
 
 # 9. Connectivity . . .
 DeclareOperation("DigraphFloydWarshall",
@@ -132,4 +135,4 @@ DeclareOperation("PartialOrderDigraphMeetOfVertices",
 # 11. DFS
 DeclareOperation("NewDFSRecord", [IsDigraph]);
 DeclareOperation("DFSDefault", [IsRecord, IsObject]);
-DeclareGlobalFunction("ExecuteDFS");
+DeclareGlobalFunction("ExecuteDFS");

gap/oper.gi

@@ -1333,6 +1333,37 @@ function(D, u, v)
   return out;
 end);
 
+InstallMethod(IsDigraphPath, "for a digraph and list",
+[IsDigraph, IsList],
+function(D, digraph_path_output)
+  if Length(digraph_path_output) <> 2 then
+    DError(["the 2nd argument (a list) must have length 2, ",
+            "but found length {}"],
+           Length(digraph_path_output));
+  fi;
+  return IsDigraphPath(D, digraph_path_output[1], digraph_path_output[2]);
+end);
+
+InstallMethod(IsDigraphPath, "for a digraph, homog. list, and homog. list",
+[IsDigraph, IsHomogeneousList, IsHomogeneousList],
+function(D, nodes, edges)
+  local a, i;
+  if Length(nodes) <> Length(edges) + 1 then
+    DError(["the 2nd and 3rd arguments (lists) are incompatible, ",
+            "expected 3rd argument of length {}, got {}"],
+           Length(nodes) - 1,
+           Length(edges));
+  fi;
+  a := OutNeighbours(D);
+  for i in [1 .. Length(edges)] do
+    if nodes[i] > Length(a) or edges[i] > Length(a[nodes[i]])
+        or a[nodes[i]][edges[i]] <> nodes[i + 1] then
+      return false;
+    fi;
+  od;
+  return true;
+end);
+
 InstallMethod(DigraphShortestPath,
 "for a digraph by out-neighbours and two pos ints",
 [IsDigraphByOutNeighboursRep, IsPosInt, IsPosInt],
@@ -2149,4 +2180,4 @@ function(record, data, start, PreOrderFunc, PostOrderFunc, AncestorFunc,
   fi;
   ExecuteDFS_C(record, data, start, PreOrderFunc, PostOrderFunc,
                AncestorFunc, CrossFunc);
-end);
+end);

tst/standard/oper.tst

@@ -2697,6 +2697,45 @@ gap> ExecuteDFS(NewDFSRecord(D), [], 3, DFSDefault, DFSDefault, DFSDefault,
 > DFSDefault);
 Error, the third argument <start> must be a vertex in your graph,
 
+# IsDigraphPath
+gap> D := Digraph(IsMutableDigraph, Combinations([1 .. 5]), IsSubset);
+<mutable digraph with 32 vertices, 243 edges>
+gap> DigraphReflexiveTransitiveReduction(D);
+<mutable digraph with 32 vertices, 80 edges>
+gap> MakeImmutable(D);
+<immutable digraph with 32 vertices, 80 edges>
+gap> IsDigraphPath(D, [1, 2, 3], []);
+Error, the 2nd and 3rd arguments (lists) are incompatible, expected 3rd argume\
+nt of length 2, got 0
+gap> IsDigraphPath(D, [1], []);
+true
+gap> IsDigraphPath(D, [1, 2], [5]);
+false
+gap> IsDigraphPath(D, [32, 31, 33], [1, 1]);
+false
+gap> IsDigraphPath(D, [32, 33, 31], [1, 1]);
+false
+gap> IsDigraphPath(D, [6, 9, 16, 17], [3, 3, 2]);
+true
+gap> IsDigraphPath(D, [33, 9, 16, 17], [3, 3, 2]);
+false
+gap> IsDigraphPath(D, [6, 9, 18, 1], [9, 10, 2]);
+false
+
+# IsDigraphPath
+gap> D := Digraph(IsMutableDigraph, Combinations([1 .. 5]), IsSubset);
+<mutable digraph with 32 vertices, 243 edges>
+gap> DigraphReflexiveTransitiveReduction(D);
+<mutable digraph with 32 vertices, 80 edges>
+gap> MakeImmutable(D);
+<immutable digraph with 32 vertices, 80 edges>
+gap> IsDigraphPath(D, DigraphPath(D, 6, 1));
+true
+gap> ForAll(List(IteratorOfPaths(D, 6, 1)), x -> IsDigraphPath(D, x));
+true
+gap> IsDigraphPath(D, []);
+Error, the 2nd argument (a list) must have length 2, but found length 0
+
 #
 gap> DIGRAPHS_StopTest();
 gap> STOP_TEST("Digraphs package: standard/oper.tst", 0);