Allow specifying vertex colours in IsDigraphHomomorphism etc. (#283)

* allow specifying colours in IsDigraphHomomorphism etc.

* linting and coverage

* refactor

* Add K tags to true.

* Update isomorph.xml

Co-authored-by: James Mitchell <james-d-mitchell@users.noreply.github.com>

doc/grahom.xml

@@ -626,6 +626,7 @@ gap> EmbeddingsDigraphs(D1, D2);
     </List>
     See also <Ref Func="GeneratorsOfEndomorphismMonoid"/>.<P/>
 
+
     If <A>col1</A> and <A>col2</A>, or <A>col</A>, are given, then they must
     represent vertex colourings; see <Ref Oper="AutomorphismGroup" Label="for a
     digraph and a homogeneous list"/> for details of the permissible values for
@@ -640,6 +641,8 @@ gap> EmbeddingsDigraphs(D1, D2);
         in the cases of the other operations.</Item>
     </List>
 
+    See also <Ref Oper="DigraphsRespectsColouring"/>.
+
     <Example><![CDATA[
 gap> src := Digraph([[1], [1, 2], [1, 3]]);
 <immutable digraph with 3 vertices, 5 edges>
@@ -763,3 +766,29 @@ true
     </Description>
   </ManSection>
 <#/GAPDoc>
+
+<#GAPDoc Label="DigraphsRespectsColouring">
+  <ManSection>
+    <Oper Name="DigraphsRespectsColouring" Arg="src, ran, x, col1, col2"/>
+    <Returns> <K>true</K> or <K>false</K>. </Returns>
+    <Description>
+      The operation <C>DigraphsRespectsColouring</C> verifies whether or not 
+      the permutation or transformation <A>x</A> respects the vertex colourings
+      <A>col1</A> and <A>col2</A> of the digraphs <A>src</A> and <A>range</A>.
+      That is, <C>DigraphsRespectsColouring</C> returns <K>true</K> if and only if for
+      all vertices <C>i</C> of <A>src</A>, <C>col1[i] = col2[i ^ x]</C>.
+      <P/>
+
+      <Example><![CDATA[
+gap> src := Digraph([[1], [1, 2]]);
+<immutable digraph with 2 vertices, 3 edges>
+gap> ran := Digraph([[1], [1, 2], [1, 3]]);
+<immutable digraph with 3 vertices, 5 edges>
+gap> DigraphsRespectsColouring(src, ran, (1, 2), [2, 1], [1, 2, 1]);
+true
+gap> DigraphsRespectsColouring(src, ran, (1, 2), [2, 1], [2, 1, 1]);
+false
+]]></Example>
+    </Description>
+  </ManSection>
+<#/GAPDoc>

doc/isomorph.xml

@@ -786,10 +786,11 @@ gap> OutNeighbours(canon);
     See also <Ref Attr="AutomorphismGroup" Label="for a digraph"
       />.<P/>
 
-    If <A>col1</A> and <A>col2</A>, or <A>col</A>, are given then they must
-    represent vertex colourings; see <Ref Oper="AutomorphismGroup" Label="for a
-    digraph and a homogeneous list"/> for details of the permissible values for
-    these argument. The homomorphism must then also have the property:
+    If <A>col1</A> and <A>col2</A>, or <A>col</A>, are given, then they must
+    represent vertex colourings; see 
+    <Ref Oper="AutomorphismGroup" Label="for a digraph and a homogeneous list"/> 
+    for details of the permissible values for
+    these arguments. The homomorphism must then also have the property:
 
     <List>
       <Item>

doc/z-chap6.xml

@@ -62,6 +62,7 @@ from} $E_a$ \emph{to} $E_b$. In this case we say that $E_a$ and $E_b$ are
     <#Include Label="EmbeddingsDigraphs">
     <#Include Label="IsDigraphHomomorphism">
     <#Include Label="IsDigraphEmbedding">
+    <#Include Label="DigraphsRespectsColouring">
     <#Include Label="GeneratorsOfEndomorphismMonoid">
     <#Include Label="DigraphColouring">
     <#Include Label="DigraphGreedyColouring">

gap/grahom.gd

@@ -87,3 +87,8 @@ DeclareOperation("IsDigraphEmbedding",
 
 DeclareOperation("IsDigraphColouring", [IsDigraph, IsList]);
 DeclareOperation("IsDigraphColouring", [IsDigraph, IsTransformation]);
+
+DeclareOperation("DigraphsRespectsColouring",
+                 [IsDigraph, IsDigraph, IsTransformation, IsList, IsList]);
+DeclareOperation("DigraphsRespectsColouring",
+                 [IsDigraph, IsDigraph, IsPerm, IsList, IsList]);

gap/grahom.gi

@@ -451,6 +451,35 @@ end);
 # IsDigraph{Homo/Epi/...}morphism
 ########################################################################
 
+# Given:
+#
+# 1) two digraphs <src> and <ran>,
+# 2) a transformation <x> mapping the vertices of <src> to <ran>, and
+# 3) two lists <cols1> and <cols2> of positive integers defining vertex
+#    colourings of <src> and <ran>,
+#
+# this operation tests whether <x> respects the colouring, i.e. whether for all
+# vertices i in <src>, cols[i] = cols[i ^ x].
+InstallMethod(DigraphsRespectsColouring,
+[IsDigraph, IsDigraph, IsTransformation, IsList, IsList],
+function(src, ran, x, cols1, cols2)
+  if Maximum(OnTuples(DigraphVertices(src), x)) > DigraphNrVertices(ran) then
+    ErrorNoReturn("the third argument <x> must map the vertices of the first ",
+                  "argument <src> into the vertices of the second argument ",
+                  "<ran>,");
+  fi;
+  DIGRAPHS_ValidateVertexColouring(DigraphNrVertices(src), cols1);
+  DIGRAPHS_ValidateVertexColouring(DigraphNrVertices(ran), cols2);
+
+  return ForAll(DigraphVertices(src), i -> cols1[i] = cols2[i ^ x]);
+end);
+
+InstallMethod(DigraphsRespectsColouring,
+[IsDigraph, IsDigraph, IsPerm, IsList, IsList],
+function(src, ran, x, cols1, cols2)
+  return DigraphsRespectsColouring(src, ran, AsTransformation(x), cols1, cols2);
+end);
+
 InstallMethod(IsDigraphHomomorphism,
 "for a digraph by out-neighbours, a digraph, and a perm",
 [IsDigraphByOutNeighboursRep, IsDigraph, IsPerm],
@@ -492,15 +521,10 @@ end);
 InstallMethod(IsDigraphHomomorphism,
 "for a digraph by out-neighbours, a digraph, a transformation, and two lists",
 [IsDigraphByOutNeighboursRep, IsDigraph, IsTransformation, IsList, IsList],
-function(src, ran, x, colours1, colours2)
-  if not IsDigraphHomomorphism(src, ran, x) then
-    return false;
-  fi;
-
-  DIGRAPHS_ValidateVertexColouring(DigraphNrVertices(src), colours1);
-  DIGRAPHS_ValidateVertexColouring(DigraphNrVertices(ran), colours2);
 
-  return ForAll(DigraphVertices(src), i -> colours1[i] = colours2[i ^ x]);
+function(src, ran, x, cols1, cols2)
+  return IsDigraphHomomorphism(src, ran, x) and
+         DigraphsRespectsColouring(src, ran, x, cols1, cols2);
 end);
 
 InstallMethod(IsDigraphEndomorphism, "for a digraph and a transformation",
@@ -521,9 +545,9 @@ end);
 
 InstallMethod(IsDigraphEpimorphism, "for digraph, digraph, and transformation",
 [IsDigraph, IsDigraph, IsTransformation, IsList, IsList],
-function(src, ran, x, c1, c2)
-  return IsDigraphHomomorphism(src, ran, x, c1, c2)
-    and OnSets(DigraphVertices(src), x) = DigraphVertices(ran);
+function(src, ran, x, cols1, cols2)
+  return IsDigraphEpimorphism(src, ran, x) and
+         DigraphsRespectsColouring(src, ran, x, cols1, cols2);
 end);
 
 InstallMethod(IsDigraphEpimorphism, "for digraph, digraph, and perm",
@@ -536,9 +560,9 @@ end);
 InstallMethod(IsDigraphEpimorphism,
 "for digraph, digraph, perm, list, and list",
 [IsDigraph, IsDigraph, IsPerm, IsList, IsList],
-function(src, ran, x, c1, c2)
-  return IsDigraphHomomorphism(src, ran, x, c1, c2)
-    and OnSets(DigraphVertices(src), x) = DigraphVertices(ran);
+function(src, ran, x, cols1, cols2)
+  return IsDigraphEpimorphism(src, ran, x)
+    and DigraphsRespectsColouring(src, ran, x, cols1, cols2);
 end);
 
 InstallMethod(IsDigraphMonomorphism,
@@ -552,38 +576,19 @@ end);
 InstallMethod(IsDigraphMonomorphism,
 "for digraph, digraph, transformation, list, list",
 [IsDigraph, IsDigraph, IsTransformation, IsList, IsList],
-function(src, ran, x, c1, c2)
-  return IsDigraphHomomorphism(src, ran, x, c1, c2)
-    and IsInjectiveListTrans(DigraphVertices(src), x);
+function(src, ran, x, cols1, cols2)
+  return IsDigraphMonomorphism(src, ran, x)
+    and DigraphsRespectsColouring(src, ran, x, cols1, cols2);
 end);
 
 InstallMethod(IsDigraphMonomorphism, "for digraph, digraph, and perm",
 [IsDigraph, IsDigraph, IsPerm], IsDigraphHomomorphism);
 
 InstallMethod(IsDigraphMonomorphism, "for digraph, digraph, perm, list, list",
-[IsDigraph, IsDigraph, IsPerm, IsList, IsList], IsDigraphHomomorphism);
-
-InstallMethod(IsDigraphEmbedding,
-"for digraph, digraph by out-neighbours, transformation, list, and list",
-[IsDigraph, IsDigraphByOutNeighboursRep, IsTransformation, IsList, IsList],
-function(src, ran, x, c1, c2)
-  local y, induced, i, j;
-  if not IsDigraphMonomorphism(src, ran, x, c1, c2) then
-    return false;
-  fi;
-  y := MappingPermListList(OnTuples(DigraphVertices(src), x),
-                           DigraphVertices(src));
-  induced := BlistList(DigraphVertices(ran), OnSets(DigraphVertices(src), x));
-  for i in DigraphVertices(ran) do
-    if induced[i] then
-      for j in OutNeighbours(ran)[i] do
-        if induced[j] and not IsDigraphEdge(src, i ^ y, j ^ y) then
-          return false;
-        fi;
-      od;
-    fi;
-  od;
-  return true;
+[IsDigraph, IsDigraph, IsPerm, IsList, IsList],
+function(src, ran, x, cols1, cols2)
+  return IsDigraphHomomorphism(src, ran, x)
+    and DigraphsRespectsColouring(src, ran, x, cols1, cols2);
 end);
 
 InstallMethod(IsDigraphEmbedding,
@@ -609,6 +614,14 @@ function(src, ran, x)
   return true;
 end);
 
+InstallMethod(IsDigraphEmbedding,
+"for digraph, digraph by out-neighbours, transformation, list, and list",
+[IsDigraph, IsDigraphByOutNeighboursRep, IsTransformation, IsList, IsList],
+function(src, ran, x, cols1, cols2)
+  return IsDigraphEmbedding(src, ran, x)
+    and DigraphsRespectsColouring(src, ran, x, cols1, cols2);
+end);
+
 InstallMethod(IsDigraphEmbedding,
 "for a digraph, a digraph by out-neighbours, and a perm",
 [IsDigraph, IsDigraphByOutNeighboursRep, IsPerm],
@@ -634,23 +647,9 @@ end);
 InstallMethod(IsDigraphEmbedding,
 "for a digraph, a digraph by out-neighbours, a perm, a list, and a list",
 [IsDigraph, IsDigraphByOutNeighboursRep, IsPerm, IsList, IsList],
-function(src, ran, x, c1, c2)
-  local y, induced, i, j;
-  if not IsDigraphHomomorphism(src, ran, x, c1, c2) then
-    return false;
-  fi;
-  y := x ^ -1;
-  induced := BlistList(DigraphVertices(ran), OnSets(DigraphVertices(src), x));
-  for i in DigraphVertices(ran) do
-    if induced[i] then
-      for j in OutNeighbours(ran)[i] do
-        if induced[j] and not IsDigraphEdge(src, i ^ y, j ^ y) then
-          return false;
-        fi;
-      od;
-    fi;
-  od;
-  return true;
+function(src, ran, x, cols1, cols2)
+  return IsDigraphEmbedding(src, ran, x)
+    and DigraphsRespectsColouring(src, ran, x, cols1, cols2);
 end);
 
 InstallMethod(IsDigraphColouring, "for a digraph by out-neighbours and a list",

gap/isomorph.gi

@@ -727,13 +727,9 @@ end);
 InstallMethod(IsDigraphIsomorphism,
 "for digraph, digraph, permutation, list, and list",
 [IsDigraph, IsDigraph, IsPerm, IsList, IsList],
-function(src, ran, x, c1, c2)
-  if IsMultiDigraph(src) or IsMultiDigraph(ran) then
-    ErrorNoReturn("the 1st and 2nd arguments <src> and <ran> must not have ",
-                  "multiple edges,");
-  fi;
-  return IsDigraphHomomorphism(src, ran, x, c1, c2)
-     and IsDigraphHomomorphism(ran, src, x ^ -1, c1, c2);
+function(src, ran, x, cols1, cols2)
+  return IsDigraphIsomorphism(src, ran, x)
+    and DigraphsRespectsColouring(src, ran, x, cols1, cols2);
 end);
 
 InstallMethod(IsDigraphAutomorphism, "for a digraph and a permutation",
@@ -759,13 +755,9 @@ end);
 InstallMethod(IsDigraphIsomorphism,
 "for digraph, digraph, transformation, list, and list",
 [IsDigraph, IsDigraph, IsTransformation, IsList, IsList],
-function(src, ran, x, c1, c2)
-  local y;
-  y := AsPermutation(RestrictedTransformation(x, DigraphVertices(src)));
-  if y = fail then
-    return false;
-  fi;
-  return IsDigraphIsomorphism(src, ran, y, c1, c2);
+function(src, ran, x, cols1, cols2)
+  return IsDigraphIsomorphism(src, ran, x)
+    and DigraphsRespectsColouring(src, ran, x, cols1, cols2);
 end);
 
 InstallMethod(IsDigraphAutomorphism, "for a digraph and a transformation",