Add TadpoleDigraph (PR #423)

* added the tadpole graph

* updated the documentation with A tags

* added the A tag

* Removed duplicated function, multigraph property and added a test to increase coverage

* changed the example in the docs to false for IsMultiDigraph

* updated the examples in the doc

* Added the changes specified in the pull request

* removed the case when n is 0

* merged with the banana graph

* Final tweaks from Wilf

Co-authored-by: Wilf Wilson <wilf@wilf-wilson.net>

doc/examples.xml

@@ -665,3 +665,40 @@ gap> D := BananaTree(3, 4);
   </Description>
 </ManSection>
 <#/GAPDoc>
+
+<#GAPDoc Label="TadpoleDigraph">
+<ManSection>
+  <Oper Name="TadpoleDigraph" Arg="[filt, ]m, n"/>
+  <Returns>A digraph.</Returns>
+  <Description>
+    The <E>Tadpole digraph</E> is the symmetric closure of the disjoint union
+    of the cycle digraph on <C>[1..<A>m</A>]</C> (the 'head' of the tadpole)
+    and the chain digraph on <C>[<A>m</A>+1..<A>m</A>+<A>n</A>]</C>
+    (the 'tail' of the tadpole), along with the additional
+    edges <C>[1, <A>m</A>+1]</C> and <C>[1, <A>m</A>+1]</C>
+    which connect the 'head' and the 'tail'. For more details on the Tadpole digraph
+    please refer to <URL>https://en.wikipedia.org/wiki/Tadpole_graph</URL>.<P/>
+
+    See <Ref Oper="DigraphSymmetricClosure"/>, <Ref Oper="DigraphDisjointUnion"/>,
+    <Ref Oper="CycleDigraph"/>, and <Ref Oper="ChainDigraph"/>. <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> TadpoleDigraph(10, 15);
+<immutable symmetric digraph with 25 vertices, 50 edges>
+gap> TadpoleDigraph(IsMutableDigraph, 5, 6);
+<mutable digraph with 11 vertices, 22 edges>
+gap> IsSymmetricDigraph(TadpoleDigraph(3, 5));
+true
+]]></Example>
+  </Description>
+</ManSection>
+<#/GAPDoc>
+

doc/z-chap2.xml

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

gap/examples.gd

@@ -81,3 +81,7 @@ DeclareOperation("HaarGraph", [IsFunction, IsPosInt]);
 DeclareConstructor("BananaTreeCons", [IsDigraph, IsPosInt, IsPosInt]);
 DeclareOperation("BananaTree", [IsPosInt, IsPosInt]);
 DeclareOperation("BananaTree", [IsFunction, IsPosInt, IsPosInt]);
+
+DeclareConstructor("TadpoleDigraphCons", [IsDigraph, IsPosInt, IsPosInt]);
+DeclareOperation("TadpoleDigraph", [IsInt, IsPosInt]);
+DeclareOperation("TadpoleDigraph", [IsFunction, IsPosInt, IsPosInt]);

gap/examples.gi

@@ -674,10 +674,43 @@ function(filt, m, n)
   return D;
 end);
 
-InstallMethod(BananaTree, "for a function and two pos ints",
+InstallMethod(BananaTree, "for a function and two positive integers",
 [IsPosInt, IsPosInt],
 {m, n} -> BananaTreeCons(IsImmutableDigraph, m, n));
 
-InstallMethod(BananaTree, "for a function and two pos ints",
+InstallMethod(BananaTree, "for a function and two positive integers",
 [IsFunction, IsPosInt, IsPosInt],
 {filt, m, n} -> BananaTreeCons(filt, m, n));
+
+InstallMethod(TadpoleDigraphCons,
+"for IsMutableDigraph and two positive integers",
+[IsMutableDigraph, IsPosInt, IsPosInt],
+function(filt, m, n)
+  local tail, graph;
+  if m < 3 then
+    ErrorNoReturn("the first argument <m> must be an integer greater than 2");
+  fi;
+  graph := DigraphSymmetricClosure(CycleDigraph(IsMutableDigraph, m));
+  tail := DigraphSymmetricClosure(ChainDigraph(IsMutable, n));
+  DigraphDisjointUnion(graph, tail);
+  DigraphAddEdges(graph, [[m, n + m], [n + m, m]]);
+  return graph;
+end);
+
+InstallMethod(TadpoleDigraph, "for a function and two positive integers",
+[IsFunction, IsPosInt, IsPosInt],
+TadpoleDigraphCons);
+
+InstallMethod(TadpoleDigraph, "for two positive integers", [IsPosInt, IsPosInt],
+{m, n} -> TadpoleDigraphCons(IsImmutableDigraph, m, n));
+
+InstallMethod(TadpoleDigraphCons,
+"for IsImmutableDigraph and two positive integers",
+[IsImmutableDigraph, IsPosInt, IsPosInt],
+function(filt, m, n)
+  local D;
+  D := MakeImmutable(TadpoleDigraph(IsMutableDigraph, m, n));
+  SetIsMultiDigraph(D, false);
+  SetIsSymmetricDigraph(D, true);
+  return D;
+end);

tst/standard/examples.tst

@@ -351,6 +351,18 @@ gap> D := BananaTree(IsMutableDigraph, 5, 3);
 gap> BananaTree(3, 1);
 Error, The second argument must be an integer greater than one
 
+# TadPoleDigraph
+gap> TadpoleDigraph(2, 2);
+Error, the first argument <m> must be an integer greater than 2
+gap> TadpoleDigraph(10, 15);
+<immutable symmetric digraph with 25 vertices, 50 edges>
+gap> TadpoleDigraph(IsMutableDigraph, 5, 6);
+<mutable digraph with 11 vertices, 22 edges>
+gap> IsSymmetricDigraph(TadpoleDigraph(3, 5));
+true
+gap> TadpoleDigraph(3, 1);
+<immutable symmetric digraph with 4 vertices, 8 edges>
+
 #
 gap> DIGRAPHS_StopTest();
 gap> STOP_TEST("Digraphs package: standard/examples.tst", 0);