Add manual documentation and tidy comments

Document the previously-undocumented user-facing API in the manual:
- Introduction chapter explaining graph backtracking and its
  relationship to BacktrackKit and vole, with cross-references into
  the BacktrackKit manual rather than duplicating its framework docs.
- "Executing a search" chapter for InfoGB and the GB_Simple* search
  functions, plus GB_CheckInitial{Group,Coset}.
- "Refiners" chapter describing the GB_Con refiner families (group,
  coset, transporter, normaliser/conjugacy) with worked examples, and
  a section on the experimental normaliser variants with the
  canonical-safety warning.
- Flesh out the Equitable Graphs chapter: a description for each of
  the None/Weak/Strong/Full consolidators.

makedoc.g now loads the package (so cross-book references resolve) and
fixes the chapter order via autodoc.files.

Tidy comments: remove commented-out debug Print statements, drop two
dangling references to files that were never committed, and rewrite
the graph-merge comment in ApplyFilters to explain why pos is forced
to fail without the leftover code fragment.

Fix two tests that loaded "graphbacktrack" instead of the full
package name.

Author: ChrisJefferson

README.md

@@ -11,15 +11,6 @@ This algorithm can be used to perform calculations in permutation groups, such a
 
 This package is intended for learning and exploring the graph backtracking algorithm. The performance is **extremely poor**. For a modern, high-performance version of this algorithm, please see the [**vole**](https://github.com/peal/vole) package.
 
-`GraphBacktracking` requires GAP version >= 4.13.0, and recent versions of the following packages (see the `PackageInfo.g` file for specific versions):
-* BacktrackKit
-* datastructures
-* digraphs
-* images
-* primgrp
-
-Additionally, [the QuickCheck package](https://github.com/ChrisJefferson/QuickCheck) is required to run all of the tests.
-
 ## Contact
 
 This package is a work in progress, both in terms of code and documentation.

gap/Equitable.gd

@@ -2,17 +2,53 @@
 #
 #! @Chapter Equitable Graphs
 #!
+#! @Section Making a partition equitable
 #!
+#! During search, the partition must be refined with respect to the
+#! current graph stack until it is <E>equitable</E>: informally, until no
+#! cell can be split by looking at how its points connect to the cells of
+#! the partition. &GraphBacktracking; offers several methods of differing
+#! strength and cost. A stronger method splits the partition at least as
+#! much as a weaker one, prunes the search tree more, but costs more per
+#! node. Which one is used is controlled by the <C>consolidator</C> field
+#! of the configuration record passed to the search functions (see
+#! <Ref Chap="Chapter_Executing_a_search"/>); the default is
+#! <Ref Oper="GB_MakeEquitableStrong" Label="for IsPartitionStack, IsTracer, IsList"/>.
 #!
-#! @Section Example Methods
-#!
-#! This section will describe the methods which can
-#! be used to make equitable partitions
+#! Each method takes a partition stack <A>ps</A>, a tracer <A>tracer</A>
+#! (see <Ref Chap="Ordered tracers" BookName="BacktrackKit"/>), and a list
+#! <A>graphs</A> of digraphs. It refines <A>ps</A> in place, recording the
+#! splits in <A>tracer</A>, and returns <K>true</K> on success or
+#! <K>false</K> if a split contradicted the tracer (a dead branch).
 
+#! @Arguments ps, tracer, graphs
 #! @Description
-#!   Given a partition stack, and a list of graphs,
-#!   make the partition equitable.
+#!   Does nothing and returns <K>true</K>: the partition is left
+#!   unchanged. Provided as a baseline (it makes graph backtracking behave
+#!   like ordinary backtracking with respect to the graphs).
 DeclareOperation("GB_MakeEquitableNone", [IsPartitionStack, IsTracer, IsList]);
+
+#! @Arguments ps, tracer, graphs
+#! @Description
+#!   Refines <A>ps</A> by repeatedly splitting each cell according to the
+#!   multiset of cells reached along out- and in-edges of each graph,
+#!   iterating to a fixed point. This is the classical equitable-partition
+#!   refinement applied to each graph in turn.
 DeclareOperation("GB_MakeEquitableWeak", [IsPartitionStack, IsTracer, IsList]);
+
+#! @Arguments ps, tracer, graphs
+#! @Description
+#!   A stronger refinement than <Ref Oper="GB_MakeEquitableWeak" Label="for IsPartitionStack, IsTracer, IsList"/>: it
+#!   distinguishes points using the combined edge information across all
+#!   graphs simultaneously, rather than one graph at a time. This is the
+#!   default consolidator.
 DeclareOperation("GB_MakeEquitableStrong", [IsPartitionStack, IsTracer, IsList]);
+
+#! @Arguments ps, tracer, graphs
+#! @Description
+#!   The strongest (and most expensive) refinement: it builds a single
+#!   digraph encoding the whole graph stack, computes its automorphism
+#!   group and orbits, and splits the partition by those orbits. This can
+#!   prune branches the cheaper methods miss, at a substantial cost per
+#!   node.
 DeclareOperation("GB_MakeEquitableFull", [IsPartitionStack, IsTracer, IsList]);

gap/Equitable.gi

@@ -13,22 +13,18 @@ InstallMethod(GB_MakeEquitableWeak, [IsPartitionStack, IsTracer, IsList],
         while cellcount <> PS_Cells(ps) and PS_Cells(ps) <> PS_ExtendedPoints(ps) do
             cellcount := PS_Cells(ps);
             for graph in graphlist do
-                #Print(graph,"\n");
                 hm := [];
                 for v in [1..PS_ExtendedPoints(ps)] do
                     hm[v] := List(_BTKit.OutNeighboursSafe(graph, v), {x} -> PS_CellOfPoint(ps, x));
-                    # We negate to distinguish in and out neighbours ---------v
+                    # Negate the in-neighbour cells to distinguish them from out-neighbours.
                     Append(hm[v], List(_BTKit.InNeighboursSafe(graph, v), {x} -> -PS_CellOfPoint(ps, x)));
-                    #Print(v,":",hm[v],"\n");
                     Sort(hm[v]);
                 od;
-                #Print(hm,"\n");
                 if not PS_SplitCellsByFunction(ps, tracer, {x} -> hm[x]) then
                     Info(InfoGB, 2, "EquitableWeak trace violation");
                     return false;
                 fi;
             od;
-            #Print(hm,"\n");
         od;
         return true;
 end);
@@ -62,7 +58,6 @@ InstallMethod(GB_MakeEquitableStrong, [IsPartitionStack, IsTracer, IsList],
                 Info(InfoGB, 2, "EquitableStrong trace violation");
                 return false;
             fi;
-            #Print(hm,"\n");
         od;
         return true;
 end);

gap/GraphBacktracking.gd

@@ -1,11 +1,71 @@
 #
 # GraphBacktracking
 #
-# Implementations
+# Declarations
 #
 
-#! @Description
-#!  Information about backtrack search
+#! @Chapter Introduction
+#!
+#! @Section What is &GraphBacktracking;?
+#!
+#! &GraphBacktracking; implements the graph backtracking algorithm
+#! described in the paper <Q>Computing canonical images in permutation
+#! groups with Graph Backtracking</Q>, by Christopher Jefferson, Rebecca
+#! Waldecker and Wilf A. Wilson
+#! (<URL>https://arxiv.org/abs/2209.02534</URL>). Graph backtracking
+#! generalises
+#! Leon's partition backtrack: instead of refining only an ordered
+#! partition of the points, the search also accumulates a stack of
+#! vertex- and edge-labelled graphs, which can capture constraints that a
+#! partition alone cannot. This makes it possible to solve problems such
+#! as normaliser computation and the canonical image of a graph under an
+#! arbitrary group.
+#!
+#! This package builds directly on the <Package>BacktrackKit</Package>
+#! package, and reuses its framework essentially unchanged: ordered
+#! partition stacks, tracers, constraints, the refiner protocol, and the
+#! top-level search loop. Those concepts are documented in the
+#! <Package>BacktrackKit</Package> manual and are not repeated here. This
+#! manual assumes you are familiar with them, in particular with
+#! <Ref Sect="The concept of constraints" BookName="BacktrackKit"/> and
+#! <Ref Chap="Refiners" BookName="BacktrackKit"/>, and documents only what
+#! &GraphBacktracking; adds on top.
+#!
+#! @Section Relationship to BacktrackKit and Vole
+#!
+#! Like <Package>BacktrackKit</Package>, this package exists for
+#! <E>learning and exploring</E> the algorithms. Its performance is
+#! <E>extremely poor</E> — often orders of magnitude slower than the
+#! built-in &GAP; functions for the same task. For a modern,
+#! high-performance implementation of graph backtracking, use the
+#! <Package>vole</Package> package
+#! (<URL>https://github.com/peal/vole</URL>) instead.
+#!
+#! The one substantive extension to the <Package>BacktrackKit</Package>
+#! refiner protocol is that a &GraphBacktracking; refiner may, in addition
+#! to splitting cells of the partition, emit <E>graphs</E>. A value
+#! returned by a refiner's <C>refine</C> functions (see
+#! <Ref Sect="The record refine" BookName="BacktrackKit"/>) may be a
+#! record with the components:
+#! * <C>graph</C> — a <Package>Digraphs</Package> digraph that is added to
+#!   the graph stack; and/or
+#! * <C>vertlabels</C> — a list giving an initial colour for each vertex.
+#!
+#! The graph stack is then made equitable (see
+#! <Ref Chap="Chapter_Equitable_Graphs"/>) and contributes to the branching and
+#! pruning of the search in the same way the partition does.
+
+#! @Chapter Executing a search
+#!
+#! @Section Information and diagnostics
+#!
+#! &GraphBacktracking; reports diagnostic information through the info
+#! class <C>InfoGB</C>, which is set equal to the
+#! <Package>BacktrackKit</Package> info class
+#! <Ref InfoClass="InfoBTKit" BookName="BacktrackKit"/>; raising the level
+#! of either (with <C>SetInfoLevel</C>) therefore raises both. Higher
+#! levels print progressively more detail about the progress of the
+#! search.
 InfoGB := InfoBTKit;
 
 # From init.g

gap/GraphBacktracking.gi

@@ -86,9 +86,12 @@ InstallMethod(ApplyFilters, [IsGBState, IsTracer, IsObject],
                 fi;
             fi;
             if IsBound(f.graph) then
-                # TODO (maybe) -- this skipping of merged graphs ignores
-                # vertex colourings.
-                pos := fail; # This isn't valid for normalisers (and others): Position(state!.raw_graphs, f.graph);
+                # We never merge a repeated graph: refiners such as the
+                # normaliser push graphs that must all be kept, and
+                # deduplicating by Position would also ignore vertex
+                # colourings. So pos is always fail; the merge branch
+                # below is kept for the day we can merge safely.
+                pos := fail;
                 if pos = fail then
                     Add(state!.raw_graphs, f.graph);
                     if PS_Points(state!.ps) < DigraphNrVertices(f.graph) then

gap/constraints/canonicalconstraints.g

@@ -15,7 +15,6 @@ GB_Con.InCosetSimple := function(group, perm)
                 array[j] := i;
             od;
         od;
-        #Print(group, pointlist, orbs, array, "\n");
         return rec(points := array, graphs := graphs);
     end;
 

gap/constraints/normaliser.g

@@ -477,7 +477,7 @@ _BTKit.findRegularCharacteristicSubgroup := function(group, sizeCap)
     # uniqueness check fails. Skipping early also dodges a GAP-internal
     # performance pathology in which CharacteristicSubgroups hangs
     # after Size/Orbits have been called on Derived/Fitting/Centre
-    # subgroups (reproducer in tst/benchmarks/refiner-sweep-slow.g).
+    # subgroups.
     # This is a heuristic: there exist exotic H where two equal-length
     # orbits have non-isomorphic H-actions and no Aut(H)-swap exists,
     # in which case we may miss a usable F. But those cases are rare
@@ -544,7 +544,7 @@ end;
 # regOrbit, fp_R = g(fp_L), and the deduction-set D_R = g(D_L). The
 # labels match between sides because BFS-position(p) on the left
 # equals BFS-position(g(p)) on the right (the generator-correspondence
-# h_i^g = h_i' under conjugation by g — see notes/phase-c-notes.md).
+# h_i^g = h_i' under conjugation by g).
 # The branch-point proposal points to corresponding cells (same cell
 # index) on both sides since cell indices are g-equivariant for valid
 # candidates.