Add BookDigraph (PR #445)

doc/examples.xml

@@ -706,3 +706,40 @@ true
 </ManSection>
 <#/GAPDoc>
 
+<#GAPDoc Label="BookDigraph">
+<ManSection>
+  <Oper Name="BookDigraph" Arg="[filt, ]m"/>
+  <Returns>A digraph.</Returns>
+  <Description>
+    The <E>Book digraph</E> is the Cartesian product of a complete digraph with 2 vertices
+    (as the "Book Spine") and the <M><A>m</A>+1</M> star digraph (as the "Pages").
+    For more details on the Book digraph please refer to <URL>https://mathworld.wolfram.com/BookGraph.html</URL>.<P/>
+
+    See <Ref Func="DigraphCartesianProduct" Label="for a positive number of digraphs"/>,
+    <Ref Oper="CompleteDigraph"/>, and <Ref Oper="StarDigraph"/>. <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/>
+
+    <Example><![CDATA[
+gap> BookDigraph(1);
+<immutable bipartite symmetric digraph with bicomponent sizes 2 and 2>
+gap> BookDigraph(2);
+<immutable bipartite symmetric digraph with bicomponent sizes 3 and 3>
+gap> BookDigraph(IsMutable, 12);
+<mutable digraph with 26 vertices, 74 edges>
+gap> BookDigraph(7);
+<immutable bipartite symmetric digraph with bicomponent sizes 8 and 8>
+gap> IsSymmetricDigraph(BookDigraph(24));
+true
+gap> IsBipartiteDigraph(BookDigraph(24));
+true
+]]></Example>
+  </Description>
+</ManSection>
+<#/GAPDoc>

doc/z-chap2.xml

@@ -97,6 +97,7 @@
     <#Include Label="KnightsGraph">
     <#Include Label="StarDigraph">
     <#Include Label="TadpoleDigraph">
+    <#Include Label="BookDigraph">
   </Section>
 
 </Chapter>

gap/examples.gd

@@ -86,3 +86,7 @@ DeclareOperation("BananaTree", [IsFunction, IsPosInt, IsPosInt]);
 DeclareConstructor("TadpoleDigraphCons", [IsDigraph, IsPosInt, IsPosInt]);
 DeclareOperation("TadpoleDigraph", [IsInt, IsPosInt]);
 DeclareOperation("TadpoleDigraph", [IsFunction, IsPosInt, IsPosInt]);
+
+DeclareConstructor("BookDigraphCons", [IsDigraph, IsPosInt]);
+DeclareOperation("BookDigraph", [IsPosInt]);
+DeclareOperation("BookDigraph", [IsFunction, IsPosInt]);

gap/examples.gi

@@ -712,3 +712,31 @@ function(filt, m, n)
   SetIsSymmetricDigraph(D, true);
   return D;
 end);
+
+InstallMethod(BookDigraphCons,
+"for IsMutableDigraph and one positive integer",
+[IsMutableDigraph, IsPosInt],
+function(filt, m)
+  local book;
+  book := CompleteDigraph(IsMutable, 2);
+  return DigraphCartesianProduct(book, StarDigraph(IsMutable, m + 1));
+end);
+
+InstallMethod(BookDigraph, "for a function and one positive integer",
+[IsFunction, IsPosInt],
+BookDigraphCons);
+
+InstallMethod(BookDigraph, "for one positive integer", [IsPosInt],
+{m} -> BookDigraphCons(IsImmutableDigraph, m));
+
+InstallMethod(BookDigraphCons,
+"for IsImmutableDigraph and one positive integer",
+[IsImmutableDigraph, IsPosInt],
+function(filt, m)
+  local D;
+  D := MakeImmutable(BookDigraph(IsMutableDigraph, m));
+  SetIsMultiDigraph(D, false);
+  SetIsSymmetricDigraph(D, true);
+  SetIsBipartiteDigraph(D, true);
+  return D;
+end);

tst/standard/examples.tst

@@ -365,6 +365,22 @@ true
 gap> TadpoleDigraph(3, 1);
 <immutable symmetric digraph with 4 vertices, 8 edges>
 
+# BookDigraph
+gap> BookDigraph(1);
+<immutable bipartite symmetric digraph with bicomponent sizes 2 and 2>
+gap> BookDigraph(2);
+<immutable bipartite symmetric digraph with bicomponent sizes 3 and 3>
+gap> BookDigraph(7);
+<immutable bipartite symmetric digraph with bicomponent sizes 8 and 8>
+gap> BookDigraph(12);
+<immutable bipartite symmetric digraph with bicomponent sizes 13 and 13>
+gap> BookDigraph(IsMutable, 12);
+<mutable digraph with 26 vertices, 74 edges>
+gap> IsSymmetricDigraph(BookDigraph(24));
+true
+gap> IsBipartiteDigraph(BookDigraph(32));
+true
+
 #
 gap> DIGRAPHS_StopTest();
 gap> STOP_TEST("Digraphs package: standard/examples.tst", 0);