Add SquareGridGraph and TriangularGridGraph (PR #416)

doc/examples.xml

@@ -310,6 +310,91 @@ gap> GeneralisedPetersenGraph(IsMutableDigraph, 9, 4);
 </ManSection>
 <#/GAPDoc>
 
+<#GAPDoc Label="SquareGridGraph">
+<ManSection>
+  <Oper Name="SquareGridGraph" Arg="[filt, ]n, k"/>
+  <Oper Name="GridGraph" Arg="[filt, ]n, k"/>
+  <Returns>A digraph.</Returns>
+  <Description>
+    If <A>n</A> and <A>k</A> are positive integers, then this operation returns
+    a square grid graph of dimension <A>n</A> by <A>k</A>. <P/>
+
+    A <E>square grid graph</E> of dimension <A>n</A> by <A>k</A> is the
+    <Ref Func="DigraphCartesianProduct"
+      Label="for a positive number of digraphs" /> of the
+    symmetric closures of the chain digraphs with <A>n</A> and <A>k</A>
+    vertices; see <Ref Oper="DigraphSymmetricClosure"/> and
+    <Ref Oper="ChainDigraph"/>.  <P/>
+
+    In particular, the <C><A>n</A> * <A>k</A></C>  vertices can be arranged
+    into an <A>n</A> by <A>k</A> grid such that two vertices are adjacent in
+    the digraph if and only if they are orthogonally adjacent in the grid.
+    The correspondence between vertices and grid positions is given by
+    <Ref Oper="DigraphVertexLabels"/>.  <P/>
+
+    See <URL>https://en.wikipedia.org/wiki/Lattice_graph</URL>
+    for more information.  <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> SquareGridGraph(5, 5);
+<immutable connected bipartite symmetric digraph with bicomponent size\
+s 13 and 12>
+gap> GridGraph(IsMutable, 3, 4);
+<mutable digraph with 12 vertices, 34 edges>
+]]></Example>
+  </Description>
+</ManSection>
+<#/GAPDoc>
+
+<#GAPDoc Label="TriangularGridGraph">
+<ManSection>
+  <Oper Name="TriangularGridGraph" Arg="[filt, ]n, k"/>
+  <Returns>A digraph.</Returns>
+  <Description>
+    If <A>n</A> and <A>k</A> are positive integers, then this operation returns
+    a triangular grid graph of dimension <A>n</A> by <A>k</A>. <P/>
+
+    A <E>triangular grid graph</E> of dimension <A>n</A> by <A>k</A> is a
+    symmetric digraph constructed from the <Ref Oper="SquareGridGraph"/> of the
+    same dimensions, where additionally two vertices are adjacent in the digraph
+    if they are diagonally adjacent in the grid, on a particular one of the
+    diagonals.
+    The correspondence between vertices and grid positions is given by <Ref
+      Oper="DigraphVertexLabels"/>.
+    More specifically, the particular diagonal is the one such that,
+    the vertices corresponding to the grid positions <C>[2,1]</C> and
+    <C>[1,2]</C> are adjacent (if they exist),
+    but those corresponding to <C>[1,1]</C> and <C>[2,2]</C> are not. <P/>
+
+    See <URL>https://en.wikipedia.org/wiki/Lattice_graph#Other_kinds</URL>
+    for more information.  <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> TriangularGridGraph(3, 3);
+<immutable connected symmetric digraph with 9 vertices, 32 edges>
+gap> TriangularGridGraph(IsMutable, 3, 3);
+<mutable digraph with 9 vertices, 32 edges>
+]]></Example>
+  </Description>
+</ManSection>
+<#/GAPDoc>
+
 <#GAPDoc Label="StarDigraph">
 <ManSection>
   <Oper Name="StarDigraph" Arg="[filt, ]k"/>

doc/z-chap2.xml

@@ -87,6 +87,8 @@
     <#Include Label="JohnsonDigraph">
     <#Include Label="PetersenGraph">
     <#Include Label="GeneralisedPetersenGraph">
+    <#Include Label="SquareGridGraph">
+    <#Include Label="TriangularGridGraph">
     <#Include Label="HaarGraph">
     <#Include Label="KnightsGraph">
     <#Include Label="StarDigraph">

gap/examples.gd

@@ -49,6 +49,15 @@ DeclareConstructor("GeneralisedPetersenGraphCons", [IsDigraph, IsInt, IsInt]);
 DeclareOperation("GeneralisedPetersenGraph", [IsInt, IsInt]);
 DeclareOperation("GeneralisedPetersenGraph", [IsFunction, IsInt, IsInt]);
 
+DeclareConstructor("SquareGridGraphCons", [IsDigraph, IsPosInt, IsPosInt]);
+DeclareOperation("SquareGridGraph", [IsPosInt, IsPosInt]);
+DeclareOperation("SquareGridGraph", [IsFunction, IsPosInt, IsPosInt]);
+DeclareSynonym("GridGraph", SquareGridGraph);
+
+DeclareConstructor("TriangularGridGraphCons", [IsDigraph, IsPosInt, IsPosInt]);
+DeclareOperation("TriangularGridGraph", [IsPosInt, IsPosInt]);
+DeclareOperation("TriangularGridGraph", [IsFunction, IsPosInt, IsPosInt]);
+
 DeclareConstructor("StarDigraphCons", [IsDigraph, IsPosInt]);
 DeclareOperation("StarDigraph", [IsPosInt]);
 DeclareOperation("StarDigraph", [IsFunction, IsPosInt]);

gap/examples.gi

@@ -371,6 +371,83 @@ GeneralisedPetersenGraphCons);
 InstallMethod(GeneralisedPetersenGraph, "for integer, integer", [IsInt, IsInt],
 {n, k} -> GeneralisedPetersenGraphCons(IsImmutableDigraph, n, k));
 
+# This function constructs an n by k square grid graph.
+
+InstallMethod(SquareGridGraphCons,
+"for IsMutableDigraph and two positive integers",
+[IsMutableDigraph, IsPosInt, IsPosInt],
+function(filt, n, k)
+  local D1, D2;
+  D1 := DigraphSymmetricClosure(ChainDigraph(IsMutableDigraph, n));
+  D2 := DigraphSymmetricClosure(ChainDigraph(IsMutableDigraph, k));
+  return DigraphCartesianProduct(D1, D2);
+end);
+
+InstallMethod(SquareGridGraphCons,
+"for IsImmutableDigraph and two positive integers",
+[IsImmutableDigraph, IsPosInt, IsPosInt],
+function(filt, n, k)
+  local D;
+  D := MakeImmutable(SquareGridGraphCons(IsMutableDigraph, n, k));
+  SetIsMultiDigraph(D, false);
+  SetIsSymmetricDigraph(D, true);
+  SetIsBipartiteDigraph(D, n > 1 or k > 1);
+  SetIsPlanarDigraph(D, true);
+  SetIsConnectedDigraph(D, true);
+  SetDigraphHasLoops(D, false);
+  return D;
+end);
+
+InstallMethod(SquareGridGraph, "for a function and two positive integers",
+[IsFunction, IsPosInt, IsPosInt],
+SquareGridGraphCons);
+
+InstallMethod(SquareGridGraph, "for two integers", [IsPosInt, IsPosInt],
+{n, k} -> SquareGridGraphCons(IsImmutableDigraph, n, k));
+
+#  This function constructs an n by k triangular grid graph. It is the same as
+#  the square grid graph except that it adds diagonal edges.
+
+InstallMethod(TriangularGridGraphCons,
+"for IsMutableDigraph and two integers",
+[IsMutableDigraph, IsPosInt, IsPosInt],
+function(filt, n, k)
+  local D, a, b, i, j;
+  D := SquareGridGraph(IsMutableDigraph, n, k);
+  for i in [1 .. (k - 1)] do
+    for j in [1 .. (n - 1)] do
+      a := ((i - 1) * n) + j + 1;
+      b := ((i - 1) * n) + j + n;
+      DigraphAddEdge(D, a, b);
+      DigraphAddEdge(D, b, a);
+    od;
+  od;
+  return D;
+end);
+
+InstallMethod(TriangularGridGraphCons,
+"for IsImmutableDigraph and two positive integers",
+[IsImmutableDigraph, IsPosInt, IsPosInt],
+function(filt, n, k)
+  local D;
+  D := MakeImmutable(TriangularGridGraphCons(IsMutableDigraph, n, k));
+  SetIsMultiDigraph(D, false);
+  SetIsSymmetricDigraph(D, true);
+  SetIsBipartiteDigraph(D, n * k in Difference([n, k], [1]));
+  SetIsPlanarDigraph(D, true);
+  SetIsConnectedDigraph(D, true);
+  SetDigraphHasLoops(D, false);
+  return D;
+end);
+
+InstallMethod(TriangularGridGraph, "for a function and two positive integers",
+[IsFunction, IsPosInt, IsPosInt],
+TriangularGridGraphCons);
+
+InstallMethod(TriangularGridGraph, "for two positive integers",
+[IsPosInt, IsPosInt],
+{n, k} -> TriangularGridGraphCons(IsImmutableDigraph, n, k));
+
 InstallMethod(StarDigraphCons, "for IsMutableDigraph and a positive integer",
 [IsMutableDigraph, IsPosInt],
 function(filt, k)

tst/standard/examples.tst

@@ -226,6 +226,38 @@ Error, the arguments <n> and <k> must be non-negative integers,
 gap> JohnsonDigraph(IsMutableDigraph, 4, 2);
 <mutable digraph with 6 vertices, 24 edges>
 
+#  SquareGridGraph
+gap> SquareGridGraph(7, 7);
+<immutable connected bipartite symmetric digraph with bicomponent sizes 25 and\
+ 24>
+gap> SquareGridGraph(2, 4);
+<immutable connected bipartite symmetric digraph with bicomponent sizes 4 and \
+4>
+gap> SquareGridGraph(IsMutableDigraph, 5, 3);
+<mutable digraph with 15 vertices, 44 edges>
+gap> SquareGridGraph(IsImmutableDigraph, 1, 1);
+<immutable empty digraph with 1 vertex>
+gap> SquareGridGraph(1, 4);
+<immutable connected bipartite symmetric digraph with bicomponent sizes 2 and \
+2>
+gap> SquareGridGraph(2, 1);
+<immutable connected bipartite symmetric digraph with bicomponent sizes 1 and \
+1>
+
+#  TriangularGridGraph
+gap> TriangularGridGraph(3, 4);
+<immutable connected symmetric digraph with 12 vertices, 46 edges>
+gap> TriangularGridGraph(IsMutableDigraph, 7, 2);
+<mutable digraph with 14 vertices, 50 edges>
+gap> TriangularGridGraph(1, 1);
+<immutable empty digraph with 1 vertex>
+gap> TriangularGridGraph(1, 5);
+<immutable connected bipartite symmetric digraph with bicomponent sizes 3 and \
+2>
+gap> TriangularGridGraph(3, 1);
+<immutable connected bipartite symmetric digraph with bicomponent sizes 2 and \
+1>
+
 # StarDigraph
 gap> StarDigraph(IsMutable, 10);
 <mutable digraph with 10 vertices, 18 edges>