Merge branch 'amalgamDigraphs' of github.com:finnbuck/Digraphs into a…

…malgamDigraphs

.VERSION

@@ -1 +1 @@
-1.5.0
+1.5.2

CHANGELOG.md

@@ -1,9 +1,22 @@
 # CHANGELOG – Digraphs package for GAP
-Copyright © 2014-21 by Jan De Beule, Julius Jonušas, James D. Mitchell,
+Copyright © 2014-22 by Jan De Beule, Julius Jonušas, James D. Mitchell,
 Wilf A. Wilson, Michael Young et al.
 
 Licensing information can be found in the `LICENSE` file.
 
+## Version 1.5.2 (released 30/03/2022)
+
+This is a very minor release containing technical changes for maintaining compatibility with other GAP packages.
+
+## Version 1.5.1 (released 29/03/2022)
+
+This minor release contains several bugfixes and technical changes. This includes:
+
+* Bugfix: vertex labels are no longer wrongly retained when using `DigraphEdgeUnion`. This was reported by [Wilf A. Wilson][] in [Issue #496](https://github.com/digraphs/Digraphs/issues/496) and fixed by Joseph Edwards in [PR #507](https://github.com/digraphs/Digraphs/pull/507).
+* Bugfix: a segfault could be caused by calling `OutNeighbours` with an inappropriate argument. This was reported by [Wilf A. Wilson][] in [Issue #518](https://github.com/digraphs/Digraphs/issues/518) and fixed by [James D. Mitchell][] in [PR #519](https://github.com/digraphs/Digraphs/pull/519).
+* [Wilf A. Wilson][] improved the performance of `DigraphAddEdge` for digraphs without edge labels in [PR #509](https://github.com/digraphs/Digraphs/pull/509).
+* [Max Horn][] changed the declaration of the variable `Vertices` to improve compatibility with  Grape in [PR #530](https://github.com/digraphs/Digraphs/pull/530).
+
 ## Version 1.5.0 (released 27/10/2021)
 
 This is a fairly major release of the Digraphs package, containing some bugfixes and several new features. 

PackageInfo.g

@@ -1,23 +1,23 @@
 #############################################################################
 ##
 ##  PackageInfo.g
-##  Copyright (C) 2015-21                                James D. Mitchell
+##  Copyright (C) 2015-22                                James D. Mitchell
 ##
 ##  Licensing information can be found in the README.md file of this package.
 ##
 #############################################################################
 ##
 
 ##  <#GAPDoc Label="PKGVERSIONDATA">
-##  <!ENTITY VERSION                  "1.5.0">
+##  <!ENTITY VERSION                  "1.5.2">
 ##  <!ENTITY GAPVERS                  "4.10.0">
 ##  <!ENTITY GRAPEVERS                "4.8.1">
 ##  <!ENTITY IOVERS                   "4.5.1">
 ##  <!ENTITY ORBVERS                  "4.8.2">
 ##  <!ENTITY DATASTRUCTURESVERS       "0.2.5">
 ##  <!ENTITY NAUTYTRACESINTERFACEVERS "0.2">
-##  <!ENTITY ARCHIVENAME    "digraphs-1.5.0">
-##  <!ENTITY COPYRIGHTYEARS "2014-21">
+##  <!ENTITY ARCHIVENAME    "digraphs-1.5.2">
+##  <!ENTITY COPYRIGHTYEARS "2014-22">
 ##  <#/GAPDoc>
 
 _STANDREWSMATHS := Concatenation(["Mathematical Institute, North Haugh, ",
@@ -28,8 +28,8 @@ _STANDREWSCS := Concatenation(["Jack Cole Building, North Haugh, ",
 SetPackageInfo(rec(
 PackageName := "Digraphs",
 Subtitle := "Graphs, digraphs, and multidigraphs in GAP",
-Version := "1.5.0",
-Date := "27/10/2021",  # dd/mm/yyyy format
+Version := "1.5.2",
+Date := "30/03/2022",  # dd/mm/yyyy format
 License := "GPL-3.0-or-later",
 ArchiveFormats := ".tar.gz",
 

VERSIONS

@@ -1,13 +1,15 @@
 #############################################################################
 ##
 #W  VERSIONS
-#Y  Copyright (C) 2015-21                                James D. Mitchell
+#Y  Copyright (C) 2015-22                                James D. Mitchell
 ##
 ##  Licensing information can be found in the README.md file of this package.
 ##
 #############################################################################
 ##
 
+release 1.5.2 - 30/03/2022
+release 1.5.1 - 29/03/2022
 release 1.5.0 - 27/10/2021
 release 1.4.1 - 14/05/2021
 release 1.4.0 - 27/01/2021

doc/oper.xml

@@ -1535,6 +1535,36 @@ gap> DigraphShortestPath(D, 1, 1);
 </ManSection>
 <#/GAPDoc>
 
+<#GAPDoc Label="DigraphRandomWalk">
+<ManSection>
+  <Oper Name="DigraphRandomWalk" Arg="digraph, v, t"/>
+  <Returns>A pair of lists.</Returns>
+  <Description>
+    Returns a directed path corresponding to a <E>random walk</E> in the digraph
+    <A>digraph</A>, starting at vertex <A>v</A> and having length no more than
+    <A>t</A>.
+    <P/>
+
+    A random walk is defined as follows.  The path begins at <A>v</A>, and at
+    each step it follows a random edge leaving the current vertex.  It continues
+    through the digraph in this way until it has traversed <A>t</A> edges, or
+    until it reaches a vertex with no out-edges (a <E>sink</E>) and therefore
+    cannot continue.
+    <P/>
+
+    The output has the same form as that of <Ref Oper="DigraphPath"/>.
+    <P/>
+
+<Log><![CDATA[
+gap> D := Digraph([[1, 2], [3], [2, 4], [1], [2, 4]]);                
+<immutable digraph with 5 vertices, 8 edges>
+gap> DigraphRandomWalk(D, 1, 4);
+[ [ 1, 2, 3, 2, 3 ], [ 2, 1, 1, 1 ] ]
+]]></Log>
+  </Description>
+</ManSection>
+<#/GAPDoc>
+
 <#GAPDoc Label="IteratorOfPaths">
 <ManSection>
   <Oper Name="IteratorOfPaths" Arg="digraph, u, v"/>
@@ -2250,12 +2280,12 @@ true
   <A>S</A> with respect to embeddings (where the embeddings of <A>S</A> into
   <A>D1</A> and <A>D2</A> can be specified by <A>map1</A> and <A>map2</A>).
   The embedding of <A>D1</A> into <M>D_A</M> is set to always be the
-  <C>IdentityTransformation<C/>.<P/>
+  <C>IdentityTransformation</C>.<P/>
 
   Note that <C>AmalgamDigraphs</C> does not necessarily return the smallest
   possible digraph satisfying these properties. For examble, when
   <A>D1</A> and <A>D2</A> are equal, the embedding from <A>D2</A>
-  to <M>D_A</M> will not be the <C>IdentityTransformation<C/> and so
+  to <M>D_A</M> will not be the <C>IdentityTransformation</C> and so
   <M>D_A</M> could have many more vertices than the smallest possible amalgam
   of <A>D1</A> and <A>D2</A> over <A>S</A>. A less formal way to picture
   the exact form of <M>D_A</M> is to think of it as <A>D1</A> and <A>D2</A>
@@ -2264,22 +2294,17 @@ true
   <C>AmalgamDigraphs</C> returns a <E>tuple</E> of size two, with the first
   element being the digraph <M>A_D</M> and the second element being a
   transformation object which describes the embedding of <A>D2</A> into
-  <M>A_D<M>.
+  <M>A_D</M>.
 
   <Example><![CDATA[
 gap> D := CycleGraph(3);;
 gap> S := PathGraph(2);;
 gap> AmalgamDigraphs(D, D, S);
 [ <immutable digraph with 4 vertices, 10 edges>, 
   Transformation( [ 1, 2, 4, 4 ] ) ]
-gap> D := PetersonGraph();;
-gap> S := CycleGraph(5);;
-gap> AmalgamDigraphs(D, D, S);
-[ <immutable digraph with 15 vertices, 50 edges>, 
-  Transformation( [ 1, 2, 3, 4, 5, 11, 12, 13, 14, 15, 11, 12, 13, 14, 15 ] ) 
- ]
 gap> D1 := Digraph([[2, 3], [1, 3, 4], [1, 2, 4], [2, 3, 5], [4]]);;
-gap> D2 := Digraph([[2, 3], [1, 3, 4], [1, 2, 4, 5], [2, 3, 5], [3, 4]]);;
+gap> D2 := Digraph(
+>   [[2, 3], [1, 3, 4], [1, 2, 4, 5], [2, 3, 5], [3, 4]]);;
 gap> S := CycleGraph(3);;
 gap> map1 := Transformation([2, 4, 3, 4]);;
 gap> map2 := Transformation([2, 3, 4, 4]);;

doc/z-chap4.xml

@@ -68,6 +68,7 @@
     <#Include Label="VerticesReachableFrom">
     <#Include Label="DigraphPath">
     <#Include Label="DigraphShortestPath">
+    <#Include Label="DigraphRandomWalk">
     <#Include Label="Dominators">
     <#Include Label="DominatorTree">
     <#Include Label="IteratorOfPaths">

gap/grape.gi

@@ -132,7 +132,7 @@ function(D)
          "the Grape graph will have fewer\n#I  edges than the original,");
   fi;
 
-  if not DIGRAPHS_IsGrapeLoaded then
+  if not DIGRAPHS_IsGrapeLoaded() then
     Info(InfoWarning, 1, "Grape is not loaded,");
   fi;
 

gap/oper.gd

@@ -46,13 +46,13 @@ DeclareOperation("StrongProduct", [IsDigraph, IsDigraph]);
 DeclareOperation("ConormalProduct", [IsDigraph, IsDigraph]);
 DeclareOperation("HomomorphicProduct", [IsDigraph, IsDigraph]);
 DeclareOperation("LexicographicProduct", [IsDigraph, IsDigraph]);
-DeclareOperation("AmalgamDigraphs", 
+DeclareOperation("AmalgamDigraphs",
                  [IsDigraph, IsDigraph, IsDigraph,
                   IsTransformation, IsTransformation]);
-DeclareOperation("AmalgamDigraphs", 
+DeclareOperation("AmalgamDigraphs",
                  [IsDigraph, IsDigraph, IsDigraph, IsTransformation]);
-DeclareOperation("AmalgamDigraphs", 
-                 [IsDigraph, IsDigraph, IsDigraph,]);
+DeclareOperation("AmalgamDigraphs",
+                 [IsDigraph, IsDigraph, IsDigraph]);
 
 DeclareSynonym("DigraphModularProduct", ModularProduct);
 DeclareSynonym("DigraphStrongProduct", StrongProduct);
@@ -62,7 +62,7 @@ DeclareSynonym("DigraphLexicographicProduct", LexicographicProduct);
 
 DeclareGlobalFunction("DIGRAPHS_CombinationOperProcessArgs");
 DeclareOperation("DIGRAPHS_GraphProduct", [IsDigraph, IsDigraph, IsFunction]);
-DeclareOperation("NOCHECKS_AmalgamDigraphs", 
+DeclareOperation("NOCHECKS_AmalgamDigraphs",
                  [IsDigraph, IsDigraph, IsDigraph,
                   IsTransformation, IsTransformation]);
 
@@ -135,6 +135,7 @@ DeclareOperation("IteratorOfPaths", [IsList, IsPosInt, IsPosInt]);
 DeclareOperation("IteratorOfPathsNC", [IsList, IsPosInt, IsPosInt]);
 DeclareOperation("IsReachable", [IsDigraph, IsPosInt, IsPosInt]);
 DeclareOperation("DigraphLongestDistanceFromVertex", [IsDigraph, IsPosInt]);
+DeclareOperation("DigraphRandomWalk", [IsDigraph, IsPosInt, IsInt]);
 
 DeclareOperation("DigraphLayers", [IsDigraph, IsPosInt]);
 DeclareAttribute("DIGRAPHS_Layers", IsDigraph, "mutable");

gap/oper.gi

@@ -802,7 +802,7 @@ function(D1, D2, S, map1, map2)
 
   n := DigraphNrVertices(D2) + DigraphNrVertices(D1) - DigraphNrVertices(S);
 
-  # 'map' is an embedding of D2 into the final output graph. 
+  # 'map' is an embedding of D2 into the final output graph.
   # The embedding of D1 into the final output graph is the identity mapping.
 
   map := [1 .. n];
@@ -856,7 +856,7 @@ function(D1, D2, S, map1)
     if map2 = fail then
     ErrorNoReturn(
       "no embeddings could be found from the 3rd argument ",
-      "(a digraph) to the 2nd argument (a digraph)"); 
+      "(a digraph) to the 2nd argument (a digraph)");
   fi;
 
   return NOCHECKS_AmalgamDigraphs(D1, D2, S, map1, map2);
@@ -890,7 +890,7 @@ function(D1, D2, S)
   if map2 = fail then
     ErrorNoReturn(
       "no embeddings could be found from the 3rd argument ",
-      "(a digraph) to the 2nd argument (a digraph)"); 
+      "(a digraph) to the 2nd argument (a digraph)");
   fi;
 
   return NOCHECKS_AmalgamDigraphs(D1, D2, S, map1, map2);
@@ -1891,6 +1891,41 @@ function(D, v)
   return dist;
 end);
 
+InstallMethod(DigraphRandomWalk,
+"for a digraph, a pos int and a non-negative int",
+[IsDigraph, IsPosInt, IsInt],
+function(D, v, t)
+  local vertices, edge_indices, i, neighbours, index;
+
+  # Check input
+  if v > DigraphNrVertices(D) then
+    ErrorNoReturn("the 2nd argument <v> must be ",
+                  "a vertex of the 1st argument <D>,");
+  elif t < 0 then
+    ErrorNoReturn("the 3rd argument <t> must be a non-negative int,");
+  fi;
+
+  # Prepare output lists
+  vertices     := [v];
+  edge_indices := [];
+
+  # Iterate to desired length
+  for i in [1 .. t] do
+    neighbours := OutNeighboursOfVertex(D, v);
+    if IsEmpty(neighbours) then
+      break;  # Sink: path ends here
+    fi;
+    # Follow a random edge
+    index := Random(1, Length(neighbours));
+    v     := neighbours[index];
+    vertices[i + 1] := v;
+    edge_indices[i] := index;
+  od;
+
+  # Format matches that of DigraphPath
+  return [vertices, edge_indices];
+end);
+
 InstallMethod(DigraphLayers, "for a digraph, and a positive integer",
 [IsDigraph, IsPosInt],
 function(D, v)

init.g

@@ -25,14 +25,14 @@ if not IsBound(DIGRAPH_OUT_NBS) and
 fi;
 
 BindGlobal("DIGRAPHS_IsGrapeLoaded",
-           IsPackageMarkedForLoading("grape", "4.8.1"));
+           {} -> IsPackageMarkedForLoading("grape", "4.8.1"));
 
 # To avoid warnings when GRAPE is not loaded
 if not IsBound(IsGraph) then
   IsGraph := ReturnFalse;
 fi;
 if not IsBound(Vertices) then
-  Vertices := IdFunc;
+  DeclareOperation("Vertices", [IsRecord]);
 fi;
 if not IsBound(Adjacency) then
   Adjacency := IdFunc;

read.g

@@ -8,7 +8,7 @@
 #############################################################################
 ##
 
-if not DIGRAPHS_IsGrapeLoaded then
+if not DIGRAPHS_IsGrapeLoaded() then
   Add(DIGRAPHS_OmitFromTests, "Graph(");
 fi;
 

tst/standard/digraph.tst

@@ -211,7 +211,7 @@ gap> DigraphRange(gr);
 [ 2, 3, 2 ]
 gap> gr;
 <immutable digraph with 3 vertices, 3 edges>
-gap> if DIGRAPHS_IsGrapeLoaded then
+gap> if DIGRAPHS_IsGrapeLoaded() then
 >   g := Graph(gr);
 >   if not Digraph(g) = gr then
 >     Print("fail");
@@ -1663,7 +1663,7 @@ gap> MakeImmutable(D);
 # 
 gap> D := NullDigraph(10);
 <immutable empty digraph with 10 vertices>
-gap> if DIGRAPHS_IsGrapeLoaded then
+gap> if DIGRAPHS_IsGrapeLoaded() then
 >   D := Graph(D);
 >   if D <> rec(
 >       adjacencies := [[]],

tst/standard/grape.tst

@@ -129,7 +129,7 @@ rec( adjacencies := [ [ 2, 4 ] ], group := Group([ (1,3), (1,2)(3,4) ]),
   schreierVector := [ -1, 2, 1, 2 ] )
 
 #  Digraph: copying group from Grape
-gap> if DIGRAPHS_IsGrapeLoaded then
+gap> if DIGRAPHS_IsGrapeLoaded() then
 >   gr := Digraph(JohnsonGraph(5, 3));
 > else
 >   gr := JohnsonDigraph(5, 3);
@@ -140,7 +140,7 @@ gap> HasDigraphGroup(gr);
 true
 gap> DigraphGroup(gr);
 Group([ (1,7,10,6,3)(2,8,4,9,5), (4,7)(5,8)(6,9) ])
-gap> if DIGRAPHS_IsGrapeLoaded then
+gap> if DIGRAPHS_IsGrapeLoaded() then
 >   gr := Digraph(CompleteGraph(Group((1, 2, 3), (1, 2))));
 > else
 >   gr := Digraph([[2, 3], [1, 3], [1, 2]]);
@@ -150,7 +150,7 @@ gap> HasDigraphGroup(gr);
 true
 gap> DigraphGroup(gr);
 Group([ (1,2,3), (1,2) ])
-gap> if DIGRAPHS_IsGrapeLoaded then
+gap> if DIGRAPHS_IsGrapeLoaded() then
 >   gr := Digraph(Graph(Group([()]),
 >                       [1, 2, 3],
 >                       OnPoints,
@@ -252,7 +252,7 @@ true
 #  Graph
 gap> gr := Digraph([[2, 2], []]);
 <immutable multidigraph with 2 vertices, 2 edges>
-gap> if DIGRAPHS_IsGrapeLoaded then
+gap> if DIGRAPHS_IsGrapeLoaded() then
 >   Graph(gr);
 > fi;
 

tst/standard/oper.tst

@@ -1443,6 +1443,36 @@ infinity
 gap> DigraphLongestDistanceFromVertex(gr, 16);
 Error, the 2nd argument <v> must be a vertex of the 1st argument <D>,
 
+#  DigraphRandomWalk
+gap> gr := CompleteDigraph(5);
+<immutable complete digraph with 5 vertices>
+gap> path := DigraphRandomWalk(gr, 1, 100);;
+gap> Length(path[1]);
+101
+gap> ForAll(path[1], i -> i in [1 .. 5]);
+true
+gap> Length(path[2]);
+100
+gap> ForAll(path[2], i -> i in [1 .. 4]);
+true
+gap> gr := ChainDigraph(5);
+<immutable chain digraph with 5 vertices>
+gap> DigraphRandomWalk(gr, 2, 100);
+[ [ 2, 3, 4, 5 ], [ 1, 1, 1 ] ]
+gap> DigraphRandomWalk(gr, 2, 2);  
+[ [ 2, 3, 4 ], [ 1, 1 ] ]
+gap> DigraphRandomWalk(gr, 5, 100);
+[ [ 5 ], [  ] ]
+gap> gr := CompleteBipartiteDigraph(10, 8);;
+gap> DigraphRandomWalk(gr, 3, 0);           
+[ [ 3 ], [  ] ]
+gap> DigraphRandomWalk(gr, 19, 5);
+Error, the 2nd argument <v> must be a vertex of the 1st argument <D>,
+gap> DigraphRandomWalk(gr, 123, 5);
+Error, the 2nd argument <v> must be a vertex of the 1st argument <D>,
+gap> DigraphRandomWalk(gr, 3, -1); 
+Error, the 3rd argument <t> must be a non-negative int,
+
 #  DigraphLayers
 gap> gr := CompleteDigraph(4);
 <immutable complete digraph with 4 vertices>