kernel: clarify the images argument for HomomorphismDigraphsFinder

This commit adds some comments to the kernel code, an info warning, and
some doc to clarify the meaning of the <image> argument to
HomomorphismDigraphsFinder. See the discussion at:

#697

for details.

Author: james-d-mitchell

doc/grahom.xml

@@ -95,7 +95,20 @@
         This argument should be a subset of the vertices of the graph <A>D2</A>.
         <C>HomomorphismDigraphsFinder</C> only finds homomorphisms from
         <A>D1</A> to the subgraph of <A>D2</A> induced by the vertices
-        <A>image</A>.
+        <A>image</A>.<P/>
+
+        The returned homomorphisms (if any) are still "up to the action" of the
+        group specified by <A>aut_grp</A> (which is the entire automorphism
+        group by default). This might generate unexpected results. For example,
+        if <A>D1</A> has automorphism group where one orbit consists of, say,
+        <C>1</C> and <C>2</C>, then <C>HomomorphismDigraphsFinder</C> will only
+        attempt to find homomorphisms mapping <C>1</C> to <C>1</C>, and if
+        there are no such homomorphisms with image set equal to <A>image</A>,
+        then no homomorphisms will be returned (even if there is a homomorphism
+        from <A>D1</A> to <A>D2</A> mapping <C>1</C> to <C>2</C>). To ensure that
+        that <B>all</B> homomorphisms with image set equal to <A>image</A> are
+        considered it is necessary for the last argument <A>aut_grp</A> to be
+        the trivial permutation group.
       </Item>
 
       <Mark><A>partial_map</A></Mark>
@@ -133,6 +146,7 @@
         idea for this to be the <Ref Attr="DigraphWelshPowellOrder"/>, i.e.
         vertices ordered from highest to lowest degree.
       </Item>
+      <Mark><A>aut_grp</A></Mark>
       <Item>
         The optional argument <A>aut_grp</A> should be a subgroup of the
         automorphism group of <A>D2</A>. This function returns unique
@@ -149,6 +163,10 @@ gap> D := DigraphSymmetricClosure(D);
 <immutable symmetric digraph with 10 vertices, 18 edges>
 gap> HomomorphismDigraphsFinder(D, D, fail, [], infinity, 2, 0,
 > [3, 4], [], fail, fail);
+#I  WARNING you are trying to find homomorphisms by specifying a subset
+of the vertices of the target digraph. This might lead to unexpected
+results! If this happens, try passing Group(()) as the last argument.
+Please see the documentation of HomomorphismDigraphsFinder for details.
 [ Transformation( [ 3, 4, 3, 4, 3, 4, 3, 4, 3, 4 ] ),
   Transformation( [ 4, 3, 4, 3, 4, 3, 4, 3, 4, 3 ] ) ]
 gap> D2 := CompleteDigraph(6);;

src/bitarray.c

@@ -33,7 +33,7 @@
 ////////////////////////////////////////////////////////////////////////
 
 bool     LOOKUPS_INITIALISED = false;
-size_t*  NR_BLOCKS_LOOKUP   = NULL;
+size_t*  NR_BLOCKS_LOOKUP    = NULL;
 size_t*  QUOTIENT_LOOKUP     = NULL;
 size_t*  REMAINDER_LOOKUP    = NULL;
 Block*   MASK_LOOKUP         = NULL;
@@ -113,7 +113,7 @@ BitArray* new_bit_array(uint16_t const nr_bits) {
   bit_array->nr_bits = nr_bits;
   bit_array->nr_blocks =
       ((nr_bits % NR_BITS_PER_BLOCK) == 0 ? nr_bits / NR_BITS_PER_BLOCK
-                                           : nr_bits / NR_BITS_PER_BLOCK + 1);
+                                          : nr_bits / NR_BITS_PER_BLOCK + 1);
   bit_array->blocks = safe_calloc(bit_array->nr_blocks, NR_BITS_PER_BLOCK);
 
   return bit_array;
@@ -141,6 +141,7 @@ void set_bit_array_from_gap_list(BitArray* const bit_array, Obj list_obj) {
     return;
   }
   init_bit_array(bit_array, false, bit_array->nr_bits);
+  // TODO assert that bit_array->nr_bits > LEN_LIST(list_obj)?
   for (int i = 1; i <= LEN_LIST(list_obj); i++) {
     if (ISB_LIST(list_obj, i)) {
       set_bit_array_from_gap_int(bit_array, ELM_LIST(list_obj, i));

src/bitarray.h

@@ -195,4 +195,5 @@ void set_bit_array_from_gap_int(BitArray* const bit_array, Obj o);
 //! plain or dense).
 void set_bit_array_from_gap_list(BitArray* const bit_array, Obj list_obj);
 
+// void print_bit_array(BitArray const* const bit_array);
 #endif  //  DIGRAPHS_SRC_BITARRAY_H_

src/digraphs.c

@@ -57,6 +57,7 @@ Obj IsSubset;
 Obj OnTuples;
 Obj Group;
 Obj ClosureGroup;
+Obj InfoWarning;
 
 static inline bool IsAttributeStoringRep(Obj o) {
   return (CALL_1ARGS(IsAttributeStoringRepObj, o) == True ? true : false);
@@ -2253,6 +2254,7 @@ static Int InitKernel(StructInitInfo* module) {
   ImportGVarFromLibrary("OnTuples", &OnTuples);
   ImportGVarFromLibrary("Group", &Group);
   ImportGVarFromLibrary("ClosureGroup", &ClosureGroup);
+  ImportGVarFromLibrary("InfoWarning", &InfoWarning);
   /* return success                                                      */
   return 0;
 }

src/digraphs.h

@@ -35,5 +35,6 @@ extern Obj GeneratorsOfGroup;
 extern Obj IsDigraph;
 extern Obj IsMultiDigraph;
 extern Obj IsDigraphEdge;
+extern Obj InfoWarning;
 
 #endif  // DIGRAPHS_SRC_DIGRAPHS_H_

src/homos.c

@@ -25,15 +25,13 @@
 // 1. Try other bit hacks for iterating through set bits
 
 #include "homos.h"
+
 // C headers
 #include <setjmp.h>   // for longjmp, setjmp, jmp_buf
 #include <stdbool.h>  // for true, false, bool
 #include <stddef.h>   // for NULL
 #include <stdint.h>   // for uint16_t, uint64_t
 #include <stdlib.h>   // for malloc, NULL
-#ifdef DIGRAPHS_ENABLE_STATS
-#include <time.h>  // for time
-#endif
 
 // GAP headers
 #include "gap-includes.h"
@@ -50,6 +48,12 @@
 #include "safemalloc.h"       // for safe_mallov
 #include "schreier-sims.h"    // for PermColl, . . .
 
+#ifdef DIGRAPHS_ENABLE_STATS
+// This include has to come after digraphs-config.h since that's where
+// DIGRAPHS_ENABLE_STATS is defined
+#include <time.h>  // for time
+#endif
+
 ////////////////////////////////////////////////////////////////////////////////
 // 1. Macros
 ////////////////////////////////////////////////////////////////////////////////
@@ -135,6 +139,7 @@ extern Obj AutomorphismGroup;
 extern Obj IsPermGroup;
 extern Obj IsDigraphAutomorphism;
 extern Obj LargestMovedPointPerms;
+extern Obj InfoWarning;
 
 ////////////////////////////////////////////////////////////////////////////////
 // 3. Global variables
@@ -147,7 +152,6 @@ static Obj (*HOOK)(void*,  // HOOK function applied to every homo found
                    const uint16_t*);
 static void* USER_PARAM;  // a USER_PARAM for the hook
 
-// Values in MAP are restricted to those positions in IMAGE_RESTRICT
 static jmp_buf OUTOFHERE;  // so we can jump out of the deepest
 
 static bool ORDERED;  // true if the vertices of the domain/source digraph
@@ -680,6 +684,7 @@ static void find_graph_homos(uint16_t        depth,
     }
   }
   DIGRAPHS_ASSERT(get_bit_array(MAP_UNDEFINED[depth], next));
+  DIGRAPHS_ASSERT(next < GRAPH1->nr_vertices);
 
   if (rank < hint) {
     copy_bit_array(
@@ -2186,6 +2191,30 @@ Obj FuncHomomorphismDigraphsFinder(Obj self, Obj args) {
     }
   }
 
+  if (image_obj != Fail
+      && LEN_LIST(image_obj) != DigraphNrVertices(digraph2_obj)) {
+    bool warn = false;
+    if (aut_grp_obj == Fail) {
+      warn = true;
+    } else {
+      Obj gens = CALL_1ARGS(GeneratorsOfGroup, aut_grp_obj);
+      Int lmp  = INT_INTOBJ(CALL_1ARGS(LargestMovedPointPerms, gens));
+      warn     = lmp > 0;
+    }
+    if (warn) {
+      Obj msg = MakeImmString(
+          "WARNING you are trying to find homomorphisms by specifying a "
+          "subset of the vertices of the target digraph. This might lead "
+          "to unexpect results! If this happens, try passing Group(()) as the "
+          "last argument. Please see the documentation of "
+          "HomomorphismDigraphsFinder for details.");
+      Obj info_args = NEW_PLIST(T_PLIST, 1);
+      SET_ELM_PLIST(info_args, 1, msg);
+      SET_LEN_PLIST(info_args, 1);
+      InfoDoPrint(InfoWarning, INTOBJ_INT(0), info_args);
+    }
+  }
+
   // Some conditions that immediately rule out there being any homomorphisms.
   if (((INT_INTOBJ(injective_obj) == 1 || INT_INTOBJ(injective_obj) == 2)
        && ((hint_obj != Fail

tst/extreme/grahom.tst

@@ -29,8 +29,10 @@ gap> Size(Semigroup(gens));
 105120
 gap> HomomorphismDigraphsFinder(gr, gr, fail, [], infinity, fail, 0,
 > [1, 14, 28, 39, 42], [], fail, fail);;
+#I  WARNING you are trying to find homomorphisms by specifying a subset of the vertices of the target digraph. This might lead to unexpected results! If this happens, try passing Group(()) as the last argument. Please see the documentation of HomomorphismDigraphsFinder for details.
 gap> str := HomomorphismDigraphsFinder(gr, gr, fail, [], infinity, fail, 0,
 > [1, 14, 28, 39, 42], [], fail, fail);;
+#I  WARNING you are trying to find homomorphisms by specifying a subset of the vertices of the target digraph. This might lead to unexpected results! If this happens, try passing Group(()) as the last argument. Please see the documentation of HomomorphismDigraphsFinder for details.
 gap> Length(str);
 192
 
@@ -424,12 +426,14 @@ gap> HomomorphismDigraphsFinder(gr1, gr2, fail, [], 1, 25, 0, [1 .. 40],
       37, 38 ] ) ]
 gap> t := HomomorphismDigraphsFinder(gr1, gr2, fail, [], 1, 23, 0,
 > [4 .. 37], [], fail, fail, DigraphWelshPowellOrder(gr1))[1];
+#I  WARNING you are trying to find homomorphisms by specifying a subset of the vertices of the target digraph. This might lead to unexpected results! If this happens, try passing Group(()) as the last argument. Please see the documentation of HomomorphismDigraphsFinder for details.
 Transformation( [ 15, 11, 4, 7, 4, 9, 6, 17, 11, 31, 10, 7, 25, 9, 26, 22, 29,
  8, 21, 27, 25, 25, 30, 19, 18, 13, 16, 8, 5, 32, 31, 32 ] )
 gap> ForAll(DigraphEdges(gr1), e -> IsDigraphEdge(gr2, [e[1] ^ t, e[2] ^ t]));
 true
 gap> t := HomomorphismDigraphsFinder(gr1, gr2, fail, [], 1, 23, 0,
 > [6 .. 37], [], fail, fail, DigraphWelshPowellOrder(gr1))[1];
+#I  WARNING you are trying to find homomorphisms by specifying a subset of the vertices of the target digraph. This might lead to unexpected results! If this happens, try passing Group(()) as the last argument. Please see the documentation of HomomorphismDigraphsFinder for details.
 Transformation( [ 13, 20, 6, 30, 25, 24, 6, 23, 17, 30, 14, 9, 29, 11, 19, 28,
  13, 34, 32, 7, 9, 10, 18, 15, 12, 21, 7, 11, 37, 19, 31, 32, 33, 34, 35, 36,
   37 ] )

tst/standard/grahom.tst

@@ -79,6 +79,7 @@ gap> HomomorphismDigraphsFinder(gr1, gr2, fail, [], 1, 1, 1, [],
 Error, the 9th argument <partial_map> is too long, must be at most 2, found 4,
 gap> HomomorphismDigraphsFinder(gr1, gr2, fail, [], 1, 1, 1, [1], [1],
 > fail, fail);
+#I  WARNING you are trying to find homomorphisms by specifying a subset of the vertices of the target digraph. This might lead to unexpected results! If this happens, try passing Group(()) as the last argument. Please see the documentation of HomomorphismDigraphsFinder for details.
 [  ]
 gap> HomomorphismDigraphsFinder(CompleteDigraph(2),
 >                               CompleteDigraph(3),
@@ -91,24 +92,30 @@ gap> HomomorphismDigraphsFinder(CompleteDigraph(2),
 >                               [1],     # 1 -> 1
 >                               fail,    # no colours
 >                               fail);   # no colours
+#I  WARNING you are trying to find homomorphisms by specifying a subset of the vertices of the target digraph. This might lead to unexpected results! If this happens, try passing Group(()) as the last argument. Please see the documentation of HomomorphismDigraphsFinder for details.
 [ IdentityTransformation ]
 gap> HomomorphismDigraphsFinder(gr1, gr2, fail, [], 1, 3, 0, [1, 2], [1],
 > fail, fail);
+#I  WARNING you are trying to find homomorphisms by specifying a subset of the vertices of the target digraph. This might lead to unexpected results! If this happens, try passing Group(()) as the last argument. Please see the documentation of HomomorphismDigraphsFinder for details.
 [  ]
 gap> HomomorphismDigraphsFinder(gr2, gr1, fail, [], 1, 3, 0, [1, 2], [1],
 > fail, fail);
 [  ]
 gap> HomomorphismDigraphsFinder(gr1, gr2, fail, [], 1, 1, 0, [], [], fail,
 > fail);
+#I  WARNING you are trying to find homomorphisms by specifying a subset of the vertices of the target digraph. This might lead to unexpected results! If this happens, try passing Group(()) as the last argument. Please see the documentation of HomomorphismDigraphsFinder for details.
 [  ]
 gap> HomomorphismDigraphsFinder(gr1, gr2, fail, [], 1, 1, 0, [1, 2], [],
 > fail, fail);
+#I  WARNING you are trying to find homomorphisms by specifying a subset of the vertices of the target digraph. This might lead to unexpected results! If this happens, try passing Group(()) as the last argument. Please see the documentation of HomomorphismDigraphsFinder for details.
 [  ]
 gap> HomomorphismDigraphsFinder(gr1, gr2, fail, [], 1, 1, 0, [1, 2], [],
 > fail, fail);
+#I  WARNING you are trying to find homomorphisms by specifying a subset of the vertices of the target digraph. This might lead to unexpected results! If this happens, try passing Group(()) as the last argument. Please see the documentation of HomomorphismDigraphsFinder for details.
 [  ]
 gap> HomomorphismDigraphsFinder(gr1, gr2, fail, [], 1, 2, 0, [1], [], fail,
 > fail);
+#I  WARNING you are trying to find homomorphisms by specifying a subset of the vertices of the target digraph. This might lead to unexpected results! If this happens, try passing Group(()) as the last argument. Please see the documentation of HomomorphismDigraphsFinder for details.
 [  ]
 gap> HomomorphismDigraphsFinder(gr1, gr1, fail, [], 1, 2, 0, [1, 2], [],
 > fail, fail);
@@ -708,6 +715,7 @@ gap> gr := Digraph([[2, 3], [], [], [5], [], []]);
 <immutable digraph with 6 vertices, 3 edges>
 gap> HomomorphismDigraphsFinder(gr, gr, fail, [], infinity, fail, 0,
 > [1 .. 5], [], fail, fail);
+#I  WARNING you are trying to find homomorphisms by specifying a subset of the vertices of the target digraph. This might lead to unexpected results! If this happens, try passing Group(()) as the last argument. Please see the documentation of HomomorphismDigraphsFinder for details.
 [ Transformation( [ 1, 2, 3, 4, 5, 1 ] ), 
   Transformation( [ 1, 2, 3, 4, 5, 2 ] ), 
   Transformation( [ 1, 2, 3, 4, 5, 3 ] ), 
@@ -1129,6 +1137,7 @@ gap> gr := DigraphFromDigraph6String(Concatenation(
 <immutable digraph with 22 vertices, 198 edges>
 gap> t := HomomorphismDigraphsFinder(gr, gr, fail, [], 1, fail, 0,
 > [2, 6, 7, 11, 12, 13, 14, 15, 19, 20, 21], [], fail, fail)[1];
+#I  WARNING you are trying to find homomorphisms by specifying a subset of the vertices of the target digraph. This might lead to unexpected results! If this happens, try passing Group(()) as the last argument. Please see the documentation of HomomorphismDigraphsFinder for details.
 Transformation( [ 2, 13, 20, 19, 21, 19, 14, 13, 15, 14, 20, 6, 15, 21, 11,
   12, 6, 7, 7, 12, 2, 11 ] )
 gap> ForAll(DigraphEdges(gr), e -> IsDigraphEdge(gr, e[1] ^ t, e[2] ^ t));
@@ -1569,6 +1578,7 @@ gap> HomomorphismDigraphsFinder(D,
 >                               [],          # map
 >                               [1, 2, 3],   # colours1
 >                               [1, 3, 2]);  # colours2
+#I  WARNING you are trying to find homomorphisms by specifying a subset of the vertices of the target digraph. This might lead to unexpected results! If this happens, try passing Group(()) as the last argument. Please see the documentation of HomomorphismDigraphsFinder for details.
 [  ]
 gap> EmbeddingsDigraphsRepresentatives(NullDigraph(2),
 >                                      Digraph([[2, 3], [], []]));
@@ -1593,10 +1603,12 @@ gap> D := DigraphFromDigraph6String(Concatenation(
 > "HBSatQlC[TIC{iSBlo_VrO@u[_Eyk?]YS?"));;
 gap> HomomorphismDigraphsFinder(D, D, fail, [], 1, fail, 1,
 > [2, 6, 7, 11, 12, 13, 14, 15, 19, 20, 21], [], fail, fail);
+#I  WARNING you are trying to find homomorphisms by specifying a subset of the vertices of the target digraph. This might lead to unexpected results! If this happens, try passing Group(()) as the last argument. Please see the documentation of HomomorphismDigraphsFinder for details.
 [  ]
 gap> D := Digraph([[2], []]);;
 gap> HomomorphismDigraphsFinder(D, D, fail, [], 1, fail, 1,
 > [1], [], fail, fail);
+#I  WARNING you are trying to find homomorphisms by specifying a subset of the vertices of the target digraph. This might lead to unexpected results! If this happens, try passing Group(()) as the last argument. Please see the documentation of HomomorphismDigraphsFinder for details.
 [  ]
 
 # Test monomorphisms for graphs
@@ -1804,6 +1816,7 @@ gap> HomomorphismDigraphsFinder(D,
 >                               [, 3],       # map
 >                               fail,        # colours1
 >                               fail);       # colours2
+#I  WARNING you are trying to find homomorphisms by specifying a subset of the vertices of the target digraph. This might lead to unexpected results! If this happens, try passing Group(()) as the last argument. Please see the documentation of HomomorphismDigraphsFinder for details.
 [  ]
 gap> D := DigraphAddAllLoops(Digraph([[2, 3], [1], [1], [], [5]]));;
 gap> EmbeddingsDigraphsRepresentatives(NullDigraph(2), D);
@@ -2790,6 +2803,7 @@ on 1 of the group generators,
 gap> HomomorphismDigraphsFinder(NullDigraph(3), NullDigraph(510), fail, [], 1,
 > fail, true, [1, 2, 3], [1], fail, fail,
 > Group((511, 512)));
+#I  WARNING you are trying to find homomorphisms by specifying a subset of the vertices of the target digraph. This might lead to unexpected results! If this happens, try passing Group(()) as the last argument. Please see the documentation of HomomorphismDigraphsFinder for details.
 [ IdentityTransformation ]
 
 # Issue 697
@@ -2815,6 +2829,7 @@ gap> HomomorphismDigraphsFinder(H,
 > [],                     # partial_map
 > fail,                   # colors1
 > fail);
+#I  WARNING you are trying to find homomorphisms by specifying a subset of the vertices of the target digraph. This might lead to unexpected results! If this happens, try passing Group(()) as the last argument. Please see the documentation of HomomorphismDigraphsFinder for details.
 [  ]
 
 # With partial map, no hint
@@ -2829,6 +2844,7 @@ gap> HomomorphismDigraphsFinder(H,
 > [8],                     # partial_map
 > fail,                   # colors1
 > fail);
+#I  WARNING you are trying to find homomorphisms by specifying a subset of the vertices of the target digraph. This might lead to unexpected results! If this happens, try passing Group(()) as the last argument. Please see the documentation of HomomorphismDigraphsFinder for details.
 [ Transformation( [ 8, 1, 5, 7, 3, 4, 6, 8 ] ) ]
 
 # With group, no hint
@@ -2859,6 +2875,7 @@ gap> HomomorphismDigraphsFinder(H,
 > [8],                    # partial_map
 > fail,                   # colors1
 > fail);
+#I  WARNING you are trying to find homomorphisms by specifying a subset of the vertices of the target digraph. This might lead to unexpected results! If this happens, try passing Group(()) as the last argument. Please see the documentation of HomomorphismDigraphsFinder for details.
 [ Transformation( [ 8, 1, 5, 7, 3, 4, 6, 8 ] ) ]
 
 # With group, with hint