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

Author: finnbuck

.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"/>

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

@@ -49,10 +49,10 @@ DeclareOperation("LexicographicProduct", [IsDigraph, IsDigraph]);
 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;