Allow user to specify automorphisms in HomomorphismDigraphsFinder (#285)

* allow specifying colours in IsDigraphHomomorphism etc.

* linting and coverage

* allow user to specify automorphisms in HomomorphismDigraphsFinder

* replace test that fails with different GAP versions

* fixups

* Add missing comma

* Delete extra line

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

doc/grahom.xml

@@ -10,7 +10,7 @@
 
 <#GAPDoc Label="HomomorphismDigraphsFinder">
 <ManSection>
-  <Func Name="HomomorphismDigraphsFinder" Arg="D1, D2, hook, user_param, max_results, hint, injective, image, partial_map, colors1, colors2[, order]"/>
+  <Func Name="HomomorphismDigraphsFinder" Arg="D1, D2, hook, user_param, max_results, hint, injective, image, partial_map, colors1, colors2[, order, aut_grp]"/>
   <Returns>The argument <A>user_param</A>.</Returns>
   <Description>
     This function finds homomorphisms from the digraph <A>D1</A> to the digraph
@@ -19,7 +19,8 @@
 
     If <C>f</C> and <C>g</C> are homomorphisms found by
     <C>HomomorphismDigraphsFinder</C>, then <C>f</C> cannot be obtained from
-    <C>g</C> by right multiplying by an automorphism of <A>D2</A>.
+    <C>g</C> by right multiplying by an automorphism of <A>D2</A> in
+    <A>aut_grp</A>.
 
     <List>
       <Mark><A>hook</A></Mark>
@@ -125,13 +126,20 @@
       </Item>
       <Mark><A>order</A></Mark>
       <Item>
-        The optional final argument <A>order</A> specifies the order the
+        The optional argument <A>order</A> specifies the order the
         vertices in <A>D1</A> appear in the search for homomorphisms. 
         The value of this parameter can have a large impact
         on the runtime of the function. It seems in many cases to be a good
         idea for this to be the <Ref Attr="DigraphWelshPowellOrder"/>, i.e.
         vertices ordered from highest to lowest degree.
       </Item>
+      <Item>
+        The optional argument <A>aut_grp</A> should be a subgroup of the
+        automorphism group of <A>D2</A>. This function returns unique
+        representatives of the homomorphisms found up to right multiplication
+        by <A>aut_grp</A>. If this argument is not specific, it defaults to the
+        full automorphism group of <A>D2</A>, which may be costly to calculate.
+      </Item>
     </List>
 
     <Example><![CDATA[
@@ -155,7 +163,18 @@ gap> HomomorphismDigraphsFinder(D, D2, func, [Transformation([2, 2])],
 [ Transformation( [ 2, 2 ] ), 
   Transformation( [ 2, 2, 2, 3, 4, 5, 6, 2, 2, 2 ] ), 
   Transformation( [ 2, 2, 2, 3, 4, 5, 6, 2, 2, 3 ] ), 
-  Transformation( [ 2, 2, 2, 3, 4, 5, 6, 2, 2, 4 ] ) ]]]></Example>
+  Transformation( [ 2, 2, 2, 3, 4, 5, 6, 2, 2, 4 ] ) ]
+gap> HomomorphismDigraphsFinder(NullDigraph(2), NullDigraph(3), fail,
+> [], infinity, fail, 1, [1, 2, 3], fail, fail, fail, fail,
+> Group(()));
+[ IdentityTransformation, Transformation( [ 1, 3, 3 ] ), 
+  Transformation( [ 2, 1 ] ), Transformation( [ 2, 3, 3 ] ), 
+  Transformation( [ 3, 1, 3 ] ), Transformation( [ 3, 2, 3 ] ) ]
+gap> HomomorphismDigraphsFinder(NullDigraph(2), NullDigraph(3), fail,
+> [], infinity, fail, 1, [1, 2, 3], fail, fail, fail, fail,
+> Group((1, 2)));
+[ IdentityTransformation, Transformation( [ 1, 3, 3 ] ), 
+  Transformation( [ 3, 1, 3 ] ) ]]]></Example>
   </Description>
 </ManSection>
 <#/GAPDoc>
@@ -565,9 +584,13 @@ gap> EmbeddingsDigraphs(D1, D2);
 <#GAPDoc Label="IsDigraphHomomorphism">
 <ManSection>
   <Oper Name="IsDigraphHomomorphism" Arg="src, ran, x"/>
+  <Oper Name="IsDigraphHomomorphism" Arg="src, ran, x, col1, col2"/>
   <Oper Name="IsDigraphEpimorphism" Arg="src, ran, x"/>
+  <Oper Name="IsDigraphEpimorphism" Arg="src, ran, x, col1, col2"/>
   <Oper Name="IsDigraphMonomorphism" Arg="src, ran, x"/>
+  <Oper Name="IsDigraphMonomorphism" Arg="src, ran, x, col1, col2"/>
   <Oper Name="IsDigraphEndomorphism" Arg="digraph, x"/>
+  <Oper Name="IsDigraphEndomorphism" Arg="digraph, x, col"/>
   <Returns><K>true</K> or <K>false</K>.</Returns>
   <Description>
     <C>IsDigraphHomomorphism</C> returns <K>true</K> if the permutation
@@ -603,6 +626,20 @@ 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
+    these argument. The homomorphism must then also have the property:
+
+    <List>
+      <Item>
+        <C>col[i] = col[i ^ x]</C> for all vertices <C>i</C> of <A>digraph</A>,
+        in the case of <C>IsDigraphEndomorphism</C>.</Item>
+      <Item>
+        <C>col1[i] = col2[i ^ x]</C> for all vertices <C>i</C> of <A>src</A>,
+        in the cases of the other operations.</Item>
+    </List>
+
     <Example><![CDATA[
 gap> src := Digraph([[1], [1, 2], [1, 3]]);
 <immutable digraph with 3 vertices, 5 edges>
@@ -616,8 +653,18 @@ gap> IsDigraphHomomorphism(src, ran, Transformation([3, 3, 3]));
 false
 gap> IsDigraphHomomorphism(src, src, Transformation([3, 3, 3]));
 true
+gap> IsDigraphHomomorphism(src, ran, Transformation([1, 2, 2]),
+>                          [1, 2, 2], [1, 2]);
+true
+gap> IsDigraphHomomorphism(src, ran, Transformation([1, 2, 2]),
+>                          [2, 1, 1], [1, 2]);
+false
 gap> IsDigraphEndomorphism(src, Transformation([3, 3, 3]));
 true
+gap> IsDigraphEndomorphism(src, Transformation([3, 3, 3]), [1, 1, 1]);
+true
+gap> IsDigraphEndomorphism(src, Transformation([3, 3, 3]), [1, 1, 2]);
+false
 gap> IsDigraphEpimorphism(src, ran, Transformation([3, 3, 3]));
 false
 gap> IsDigraphMonomorphism(src, ran, Transformation([1, 2, 2]));
@@ -633,11 +680,13 @@ true]]></Example>
 <#GAPDoc Label="IsDigraphEmbedding">
 <ManSection>
   <Oper Name="IsDigraphEmbedding" Arg="src, ran, x"/>
+  <Oper Name="IsDigraphEmbedding" Arg="src, ran, x, col1, col2"/>
   <Returns><K>true</K> or <K>false</K>.</Returns>
   <Description>
     <C>IsDigraphEmbedding</C> returns <K>true</K> if the permutation
     or transformation <A>x</A> is a embedding of the digraph
-    <A>src</A> into the digraph <A>ran</A>.
+    <A>src</A> into the digraph <A>ran</A>, while respecting the colourings
+    <A>col1</A> and <A>col2</A> if given.
     <P/>
 
     A permutation or transformation <A>x</A> is a <E>embedding</E> of a digraph
@@ -657,6 +706,10 @@ gap> IsDigraphMonomorphism(src, ran, ());
 true
 gap> IsDigraphEmbedding(src, ran, ());
 true
+gap> IsDigraphEmbedding(src, ran, (), [2, 1], [2, 1, 1]);
+true
+gap> IsDigraphEmbedding(src, ran, (), [2, 1], [1, 2, 1]);
+false
 gap> ran := Digraph([[1, 2], [1, 2], [1, 3]]);
 <immutable digraph with 3 vertices, 6 edges>
 gap> IsDigraphMonomorphism(src, ran, IdentityTransformation);

doc/isomorph.xml

@@ -753,7 +753,9 @@ gap> OutNeighbours(canon);
 <#GAPDoc Label="IsDigraphAutomorphism">
 <ManSection>
   <Oper Name="IsDigraphIsomorphism" Arg="src, ran, x"/>
+  <Oper Name="IsDigraphIsomorphism" Arg="src, ran, x, col1, col2"/>
   <Oper Name="IsDigraphAutomorphism" Arg="digraph, x"/>
+  <Oper Name="IsDigraphAutomorphism" Arg="digraph, x, col"/>
   <Returns><K>true</K> or <K>false</K>.</Returns>
   <Description>
     <C>IsDigraphIsomorphism</C> returns <K>true</K> if the permutation or
@@ -783,6 +785,20 @@ gap> OutNeighbours(canon);
     </List>
     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:
+
+    <List>
+      <Item>
+        <C>col1[i] = col2[i ^ x]</C> for all vertices <C>i</C> of <A>src</A>,
+        for <C>IsDigraphIsomorphism</C>. </Item>
+      <Item>
+        <C>col[i] = col[i ^ x]</C> for all vertices <C>i</C> of <A>digraph</A>,
+        for <C>IsDigraphAutomorphism</C>. </Item>
+    </List>
 
     For some digraphs, it can be faster to use <C>IsDigraphAutomorphism</C>
     than to test membership in the automorphism group of <A>digraph</A>.
@@ -794,6 +810,10 @@ gap> IsDigraphAutomorphism(src, (1, 2, 3));
 false
 gap> IsDigraphAutomorphism(src, (2, 3));
 true
+gap> IsDigraphAutomorphism(src, (2, 3), [2, 1, 1]);
+true
+gap> IsDigraphAutomorphism(src, (2, 3), [2, 2, 1]);
+false
 gap> IsDigraphAutomorphism(src, (2, 3)(4, 5));
 false
 gap> IsDigraphAutomorphism(src, (1, 4));
@@ -810,6 +830,10 @@ gap> IsDigraphIsomorphism(ran, src, (1, 2));
 true
 gap> IsDigraphIsomorphism(src, Digraph([[3], [1, 3], [2]]), (1, 2, 3));
 false
+gap> IsDigraphIsomorphism(src, ran, (1, 2), [1, 2, 3], [2, 1, 3]);
+true
+gap> IsDigraphIsomorphism(src, ran, (1, 2), [1, 2, 2], [2, 1, 3]);
+false
 ]]></Example>
   </Description>
 </ManSection>

gap/grahom.gd

@@ -43,23 +43,47 @@ DeclareOperation("IsDigraphEndomorphism", [IsDigraph, IsTransformation]);
 DeclareOperation("IsDigraphHomomorphism",
                  [IsDigraph, IsDigraph, IsTransformation]);
 
+DeclareOperation("IsDigraphEndomorphism",
+                 [IsDigraph, IsTransformation, IsList]);
+DeclareOperation("IsDigraphHomomorphism",
+                 [IsDigraph, IsDigraph, IsTransformation, IsList, IsList]);
+
 DeclareOperation("IsDigraphEndomorphism", [IsDigraph, IsPerm]);
 DeclareOperation("IsDigraphHomomorphism",
                  [IsDigraph, IsDigraph, IsPerm]);
 
+DeclareOperation("IsDigraphEndomorphism",
+                 [IsDigraph, IsPerm, IsList]);
+DeclareOperation("IsDigraphHomomorphism",
+                 [IsDigraph, IsDigraph, IsPerm, IsList, IsList]);
+
 DeclareOperation("IsDigraphEpimorphism",
                  [IsDigraph, IsDigraph, IsTransformation]);
 DeclareOperation("IsDigraphMonomorphism",
                  [IsDigraph, IsDigraph, IsTransformation]);
 DeclareOperation("IsDigraphEmbedding",
                  [IsDigraph, IsDigraph, IsTransformation]);
 
+DeclareOperation("IsDigraphEpimorphism",
+                 [IsDigraph, IsDigraph, IsTransformation, IsList, IsList]);
+DeclareOperation("IsDigraphMonomorphism",
+                 [IsDigraph, IsDigraph, IsTransformation, IsList, IsList]);
+DeclareOperation("IsDigraphEmbedding",
+                 [IsDigraph, IsDigraph, IsTransformation, IsList, IsList]);
+
 DeclareOperation("IsDigraphEpimorphism",
                  [IsDigraph, IsDigraph, IsPerm]);
 DeclareOperation("IsDigraphMonomorphism",
                  [IsDigraph, IsDigraph, IsPerm]);
 DeclareOperation("IsDigraphEmbedding",
                  [IsDigraph, IsDigraph, IsPerm]);
 
+DeclareOperation("IsDigraphEpimorphism",
+                 [IsDigraph, IsDigraph, IsPerm, IsList, IsList]);
+DeclareOperation("IsDigraphMonomorphism",
+                 [IsDigraph, IsDigraph, IsPerm, IsList, IsList]);
+DeclareOperation("IsDigraphEmbedding",
+                 [IsDigraph, IsDigraph, IsPerm, IsList, IsList]);
+
 DeclareOperation("IsDigraphColouring", [IsDigraph, IsList]);
 DeclareOperation("IsDigraphColouring", [IsDigraph, IsTransformation]);