examples: add pancakes

doc/examples.xml

@@ -309,3 +309,47 @@ gap> GeneralisedPetersenGraph(IsMutableDigraph, 9, 4);
   </Description>
 </ManSection>
 <#/GAPDoc>
+
+<#GAPDoc Label="PancakeGraph">
+<ManSection>
+  <Oper Name="PancakeGraph" Arg="[filt, ]n"/>
+  <Returns>A digraph.</Returns>
+  <Description>
+    If <A>n</A> is a positive integer, then this operation returns
+    the <E>Pancake graph</E> with <M>n!</M> vertices and <M>n!(n - 1)</M>
+    directed edges. The <M>n</M>th Pancake graph is the Cayley graph of the
+    symmetric group acting on <C>[1 .. <A>n</A>]</C> with respect to the
+    generating set consisting of the <Q>prefix reversals</Q>. This generating
+    set has consists of the permutations <C>p2</C>, <C>p3</C>, ...,
+    <C>p<A>n</A></C> where <C>ListPerm(pi, <A>n</A>)</C> is the concatenation
+    of <C>[i, i -1 .. 1]</C> and <C>[i + 1 .. <A>n</A>]</C>. 
+    <P/>
+
+    If the optional first argument <A>filt</A> is present, then this should
+    specify the category or representation the digraph being created will
+    belong to. For example, if <A>filt</A> is <Ref Filt="IsMutableDigraph"/>,
+    then the digraph being created will be mutable, if <A>filt</A> is <Ref
+    Filt="IsImmutableDigraph"/>, then the digraph will be immutable. 
+    If the optional first argument <A>filt</A> is not present, then <Ref
+    Filt="IsImmutableDigraph"/> is used by default.<P/>
+
+    See <URL>https://en.wikipedia.org/wiki/Pancake_graph</URL> for further
+    details. 
+
+<Example><![CDATA[
+gap> D := PancakeGraph(5);
+<immutable Hamiltonian connected symmetric digraph with 120 vertices, \
+480 edges>
+gap> DigraphUndirectedGirth(D);
+6
+gap> ChromaticNumber(D);
+3
+gap> IsHamiltonianDigraph(D);
+true
+gap> IsCayleyDigraph(D);
+true
+gap> IsVertexTransitive(D);
+true]]></Example>
+  </Description>
+</ManSection>
+<#/GAPDoc>

doc/z-chap2.xml

@@ -87,6 +87,7 @@
     <#Include Label="JohnsonDigraph">
     <#Include Label="PetersenGraph">
     <#Include Label="GeneralisedPetersenGraph">
+    <#Include Label="PancakeGraph">
   </Section>
 
 </Chapter>

gap/examples.gd

@@ -48,3 +48,8 @@ DeclareOperation("PetersenGraph", [IsFunction]);
 DeclareConstructor("GeneralisedPetersenGraphCons", [IsDigraph, IsInt, IsInt]);
 DeclareOperation("GeneralisedPetersenGraph", [IsInt, IsInt]);
 DeclareOperation("GeneralisedPetersenGraph", [IsFunction, IsInt, IsInt]);
+
+DeclareConstructor("PancakeGraphCons", [IsDigraph, IsPosInt]);
+DeclareOperation("PancakeGraph", [IsPosInt]);
+DeclareOperation("PancakeGraph", [IsFunction, IsPosInt]);
+

gap/examples.gi

@@ -370,3 +370,39 @@ GeneralisedPetersenGraphCons);
 
 InstallMethod(GeneralisedPetersenGraph, "for integer, integer", [IsInt, IsInt],
 {n, k} -> GeneralisedPetersenGraphCons(IsImmutableDigraph, n, k));
+
+BindGlobal("DIGRAPHS_PrefixReversalGroup",
+function(n)
+  local id, A, i;
+  if n = 1 then
+    return Group(());
+  fi;
+  id := [1 .. n];
+  A := [];
+  for i in [2 .. n] do
+    id{[1 .. i]} := [i, i - 1 .. 1];
+    Add(A, PermList(id));
+  od;
+  return Group(A);
+end);
+
+InstallMethod(PancakeGraphCons, "for IsMutableDigraph and pos int",
+[IsMutableDigraph, IsPosInt],
+{filt, n} -> CayleyDigraph(IsMutableDigraph, DIGRAPHS_PrefixReversalGroup(n)));
+
+InstallMethod(PancakeGraphCons, "for IsImmutableDigraph and pos int",
+[IsImmutableDigraph, IsPosInt],
+function(filt, n)
+  local D;
+  D := CayleyDigraph(IsImmutableDigraph, DIGRAPHS_PrefixReversalGroup(n));
+  SetIsMultiDigraph(D, false);
+  SetIsSymmetricDigraph(D, true);
+  SetIsHamiltonianDigraph(D, true);
+  return D;
+end);
+
+InstallMethod(PancakeGraph, "for a function and pos int",
+[IsFunction, IsPosInt], PancakeGraphCons);
+
+InstallMethod(PancakeGraph, "for a pos int",
+[IsPosInt], n -> PancakeGraphCons(IsImmutableDigraph, n));

gap/grape.gd

@@ -11,8 +11,13 @@
 DeclareOperation("Graph", [IsDigraph]);
 
 #  Cayley digraphs
+DeclareConstructor("CayleyDigraphCons", [IsDigraph, IsGroup, IsList]);
+
 DeclareOperation("CayleyDigraph", [IsGroup]);
 DeclareOperation("CayleyDigraph", [IsGroup, IsList]);
+DeclareOperation("CayleyDigraph", [IsFunction, IsGroup]);
+DeclareOperation("CayleyDigraph", [IsFunction, IsGroup, IsList]);
+
 DeclareAttribute("GroupOfCayleyDigraph", IsCayleyDigraph);
 DeclareAttribute("SemigroupOfCayleyDigraph", IsCayleyDigraph);
 DeclareAttribute("GeneratorsOfCayleyDigraph", IsCayleyDigraph);

gap/grape.gi

@@ -91,33 +91,65 @@ function(imm, G, obj, act, adj)
   return D;
 end);
 
-InstallMethod(CayleyDigraph, "for a group with generators",
-[IsGroup, IsHomogeneousList],
-function(G, gens)
-  local adj, D;
-
+InstallMethod(CayleyDigraphCons,
+"for IsMutableDigraph, group, and list of elements",
+[IsMutableDigraph, IsGroup, IsHomogeneousList],
+function(filt, G, gens)
   if not IsFinite(G) then
     ErrorNoReturn("the 1st argument <G> must be a finite group,");
   elif not ForAll(gens, x -> x in G) then
     ErrorNoReturn("the 2nd argument <gens> must consist of elements of the ",
                   "1st argument,");
   fi;
+  return Digraph(IsMutableDigraph,
+                 G,
+                 AsList(G),
+                 OnLeftInverse,
+                 {x, y} -> x ^ -1 * y in gens);
+end);
 
-  adj := function(x, y)
-    return x ^ -1 * y in gens;
-  end;
+InstallMethod(CayleyDigraphCons,
+"for IsImmutableDigraph, group, and list of elements",
+[IsImmutableDigraph, IsGroup, IsHomogeneousList],
+function(filt, G, gens)
+  # This method is a duplicate of the one above because the method for Digraph
+  # sets some additional attributes if IsImmutableDigraph is passed as 1st
+  # argument, and so we don't want to make a mutable version of the returned
+  # graph, and then make it immutable, because then those attributes won't be
+  # set.
+  local D;
+  if not IsFinite(G) then
+    ErrorNoReturn("the 1st argument <G> must be a finite group,");
+  elif not ForAll(gens, x -> x in G) then
+    ErrorNoReturn("the 2nd argument <gens> must consist of elements of the ",
+                  "1st argument,");
+  fi;
+  D := Digraph(IsImmutableDigraph,
+               G,
+               AsList(G),
+               OnLeftInverse,
+               {x, y} -> x ^ -1 * y in gens);
 
-  D := Digraph(G, AsList(G), OnLeftInverse, adj);
   SetFilterObj(D, IsCayleyDigraph);
   SetGroupOfCayleyDigraph(D, G);
   SetGeneratorsOfCayleyDigraph(D, gens);
-
   return D;
 end);
 
+InstallMethod(CayleyDigraph, "for a group and list of elements",
+[IsGroup, IsHomogeneousList],
+{G, gens} -> CayleyDigraphCons(IsImmutableDigraph, G, gens));
+
+InstallMethod(CayleyDigraph, "for a filter and group with generators",
+[IsFunction, IsGroup, IsHomogeneousList], CayleyDigraphCons);
+
 InstallMethod(CayleyDigraph, "for a group with generators",
 [IsGroup and HasGeneratorsOfGroup],
-G -> CayleyDigraph(G, GeneratorsOfGroup(G)));
+G -> CayleyDigraphCons(IsImmutableDigraph, G, GeneratorsOfGroup(G)));
+
+InstallMethod(CayleyDigraph, "for a filter and group with generators",
+[IsFunction, IsGroup and HasGeneratorsOfGroup],
+{filt, G} -> CayleyDigraphCons(filt, G, GeneratorsOfGroup(G)));
 
 InstallMethod(Graph, "for a digraph", [IsDigraph],
 function(D)

tst/standard/examples.tst

@@ -226,6 +226,18 @@ Error, the arguments <n> and <k> must be non-negative integers,
 gap> JohnsonDigraph(IsMutableDigraph, 4, 2);
 <mutable digraph with 6 vertices, 24 edges>
 
+# PancakeGraph
+gap> D := PancakeGraph(3);
+<immutable Hamiltonian connected symmetric digraph with 6 vertices, 12 edges>
+gap> ChromaticNumber(D);
+2
+gap> IsVertexTransitive(D);
+true
+gap> DigraphUndirectedGirth(D);
+6
+gap> IsHamiltonianDigraph(D);
+true
+
 #
 gap> DIGRAPHS_StopTest();
 gap> STOP_TEST("Digraphs package: standard/examples.tst", 0);

tst/standard/grape.tst

@@ -18,6 +18,12 @@ gap> group := DihedralGroup(8);
 <pc group of size 8 with 3 generators>
 gap> digraph := CayleyDigraph(group);
 <immutable digraph with 8 vertices, 24 edges>
+gap> digraph := CayleyDigraph(IsMutableDigraph, group);
+<mutable digraph with 8 vertices, 24 edges>
+gap> digraph := CayleyDigraph(IsMutableDigraph, FreeGroup(1));
+Error, the 1st argument <G> must be a finite group,
+gap> digraph := CayleyDigraph(IsMutableDigraph, group, [(2, 3)]);
+Error, the 2nd argument <gens> must consist of elements of the 1st argument,
 gap> group := DihedralGroup(IsPermGroup, 8);
 Group([ (1,2,3,4), (2,4) ])
 gap> digraph := CayleyDigraph(group);
@@ -208,6 +214,11 @@ gap> if DIGRAPHS_IsGrapeLoaded then
 gap> Digraph(SymmetricGroup(3), [1, 2, 3], OnPoints, {x, y} -> x <> y);
 <immutable digraph with 3 vertices, 6 edges>
 
+#
+gap> Digraph(IsSemigroup, SymmetricGroup(3), [1, 2, 3], OnPoints, 
+> {x, y} -> x <> y);
+Error, <imm> must be IsMutableDigraph or IsImmutableDigraph
+
 #
 gap> DIGRAPHS_StopTest();
 gap> STOP_TEST("Digraphs package: standard/grape.tst", 0);