From 781960a81728292c7b1aecdfbc3a6086537386d4 Mon Sep 17 00:00:00 2001
From: Lea Racine <35891709+LRacine@users.noreply.github.com>
Date: Mon, 12 Apr 2021 16:09:28 +0100
Subject: [PATCH] Add `BookDigraph` (PR #445)

---
 doc/examples.xml          | 37 +++++++++++++++++++++++++++++++++++++
 doc/z-chap2.xml           |  1 +
 gap/examples.gd           |  4 ++++
 gap/examples.gi           | 28 ++++++++++++++++++++++++++++
 tst/standard/examples.tst | 16 ++++++++++++++++
 5 files changed, 86 insertions(+)

diff --git a/doc/examples.xml b/doc/examples.xml
index 1423c24a0..61b3e2c29 100644
--- a/doc/examples.xml
+++ b/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>
diff --git a/doc/z-chap2.xml b/doc/z-chap2.xml
index 4c80ca9f0..01140f706 100644
--- a/doc/z-chap2.xml
+++ b/doc/z-chap2.xml
@@ -97,6 +97,7 @@
     <#Include Label="KnightsGraph">
     <#Include Label="StarDigraph">
     <#Include Label="TadpoleDigraph">
+    <#Include Label="BookDigraph">
   </Section>
 
 </Chapter>
diff --git a/gap/examples.gd b/gap/examples.gd
index 2e9b85aa4..406ac18ae 100644
--- a/gap/examples.gd
+++ b/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]);
diff --git a/gap/examples.gi b/gap/examples.gi
index 0cae9dff9..5bb32ba7f 100644
--- a/gap/examples.gi
+++ b/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);
\ No newline at end of file
diff --git a/tst/standard/examples.tst b/tst/standard/examples.tst
index 2dd18d1a2..49bdea496 100644
--- a/tst/standard/examples.tst
+++ b/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);