grape: add vertex & edge labels to Cayley digraphs

This was originally Jan de Beule's idea.

Author: wilfwilson

doc/grape.xml

@@ -1,7 +1,7 @@
 #############################################################################
 ##
 #W  grape.xml
-#Y  Copyright (C) 2014-19                               James D. Mitchell
+#Y  Copyright (C) 2014-21                               James D. Mitchell
 ##
 ##  Licensing information can be found in the README file of this package.
 ##
@@ -51,12 +51,19 @@ true]]></Example>
   <Description>
     Let <A>G</A> be any group and let <A>gens</A> be a list of elements of
     <A>G</A>. This operation returns an immutable digraph that corresponds to
-    the Cayley graph of <A>G</A> with respect
-    <A>gens</A>. The vertices are the elements of <A>G</A>. There exists an edge
-    from the vertex <C>u</C> to the vertex <C>v</C> if and only if there exists
-    a generator <C>g</C> in <A>gens</A> such that <C>x * g = y</C>. <P/>
+    the Cayley graph of <A>G</A> with respect to <A>gens</A>. <P/>
 
-    <!-- FIXME What is the correspondence between vertices and elements? -->
+    The vertices of the digraph correspond to the elements of <A>G</A>,
+    in the order given by <C>AsList(<A>G</A>)</C>.
+    There exists an edge from vertex <C>u</C> to vertex <C>v</C>
+    if and only if there exists a generator <C>g</C> in <A>gens</A>
+    such that <C>AsList(<A>G</A>)[u] * g = AsList(<A>G</A>)[v]</C>. <P/>
+      
+    The labels of the vertices <C>u</C>, <C>v</C>, and the edge <C>[u, v]</C>
+    are the corresponding elements <C>AsList(<A>G</A>)[u]</C>,
+    <C>AsList(<A>G</A>)[v]</C>, and generator <C>g</C>, respectively;
+    see <Ref Oper="DigraphVertexLabel"/> and <Ref Oper="DigraphEdgeLabel"/>.
+    <P/>
 
     If the optional second argument <A>gens</A> is not present, then the
     generators of <A>G</A> are used by default.<P/>

gap/grape.gi

@@ -1,7 +1,7 @@
 #############################################################################
 ##
 ##  grape.gi
-##  Copyright (C) 2019                                   James D. Mitchell
+##  Copyright (C) 2019-21                                James D. Mitchell
 ##
 ##  Licensing information can be found in the README file of this package.
 ##
@@ -111,6 +111,8 @@ function(G, gens)
   SetFilterObj(D, IsCayleyDigraph);
   SetGroupOfCayleyDigraph(D, G);
   SetGeneratorsOfCayleyDigraph(D, gens);
+  SetDigraphEdgeLabels(D, ListWithIdenticalEntries(Size(G), gens));
+  SetDigraphVertexLabels(D, AsList(G));
 
   return D;
 end);

tst/standard/grape.tst

@@ -1,7 +1,7 @@
 #############################################################################
 ##
 #W  standard/grape.tst
-#Y  Copyright (C) 2019                                   James D. Mitchell
+#Y  Copyright (C) 2019-21                                James D. Mitchell
 ##
 ##  Licensing information can be found in the README file of this package.
 ##
@@ -18,6 +18,14 @@ gap> group := DihedralGroup(8);
 <pc group of size 8 with 3 generators>
 gap> digraph := CayleyDigraph(group);
 <immutable digraph with 8 vertices, 24 edges>
+gap> DigraphVertexLabels(digraph) = AsList(group);
+true
+gap> DigraphEdgeLabels(digraph) =
+> ListWithIdenticalEntries(Size(group), GeneratorsOfGroup(group));
+true
+gap> ForAll(DigraphEdges(digraph), e -> AsList(group)[e[1]]
+> * DigraphEdgeLabel(digraph, e[1], e[2]) = AsList(group)[e[2]]);
+true
 gap> group := DihedralGroup(IsPermGroup, 8);
 Group([ (1,2,3,4), (2,4) ])
 gap> digraph := CayleyDigraph(group);