Add documentation for function IsVertexColouring.

Add documentation for function GRAPE_ExactSetCover,
and put this documentation in new file auxil.tex.
Move documentation for function SmallestImageSet to auxil.tex
and delete file smallestim.tex.

doc/auxil.tex

@@ -0,0 +1,101 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+%A  auxil.tex           GRAPE documentation             Leonard Soicher
+%
+%
+%
+\def\GRAPE{\sf GRAPE}
+\def\nauty{\it nauty}
+\def\G{\Gamma}
+\def\Aut{{\rm Aut}\,}
+\def\x{\times}
+\Chapter{Auxiliary functions}
+
+This chapter documents some auxiliary functions used in {\GRAPE},
+which may be of wider interest. 
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\Section{Steve Linton's Function SmallestImageSet}
+
+\>SmallestImageSet( <G>, <S> )
+\>SmallestImageSet( <G>, <S>, <H> )
+
+Let <G> be a permutation group on $\{1,\ldots,n\}$, and let <S>
+be a subset of $\{1,\ldots,n\}$. Then this function returns the
+lexicographically least set in the <G>-orbit of <S>, with respect to the
+action `OnSets', without explicitly computing this (possibly huge) orbit.
+
+Thus, if <C> is a list of subsets of $\{1,\ldots,n\}$ and we
+want to determine a set of (canonical) representatives for the
+distinct <G>-orbits of the elements of <C>, we can do this as
+`Set(<C>,c->SmallestImageSet(<G>,c))'.
+
+If the setwise stabilizer in <G> of <S> is known, then this should be
+given as the optional third parameter, to avoid the recomputation of
+this stabilizer.
+
+The function `SmallestImageSet' was written by Steve Linton, based
+on his algoritm described in \cite{Lin04}. 
+
+\beginexample
+gap> J:=JohnsonGraph(12,5);;
+gap> OrderGraph(J);
+792
+gap> G:=J.group;;
+gap> Size(G);
+479001600
+gap> S:=[67,93,100,204,677];;
+gap> SmallestImageSet(G,S);
+[ 1, 2, 22, 220, 453 ]
+\endexample
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\Section{Exact set-cover}
+
+\>GRAPE_ExactSetCover( <G>, <blocks>, <n> )
+\>GRAPE_ExactSetCover( <G>, <blocks>, <n>, <H> )
+
+Suppose <n> is a positive integer, <G> is a permutation group
+on $\{1,\ldots,n\}$, <blocks> is a set of non-empty subsets
+of $\{1,\ldots,n\}$, and the optional parameter <H> (default:
+`Group(())') is a subgroup of <G>. 
+
+Then this function returns an <H>-invariant exact 
+set-cover of $\{1,\ldots,\}$, by elements from 
+`Concatenation(Orbits(<G>,<blocks>,OnSets))', if such a cover exists,
+and returns  `fail'  otherwise. An exact set-cover is given as a set of
+sets forming a partition of $\{1,\ldots,n\}$.
+
+\beginexample
+gap> n:=10;;
+gap> G:=PSL(2,5);
+Group([ (3,5)(4,6), (1,2,5)(3,4,6) ])
+gap> GRAPE_ExactSetCover(G,[[1,2,3]],6);
+fail
+gap> G:=PGL(2,5);
+Group([ (3,6,5,4), (1,2,5)(3,4,6) ])
+gap> GRAPE_ExactSetCover(G,[[1,2,3]],6);
+[ [ 1, 2, 3 ], [ 4, 5, 6 ] ]
+gap> n:=280;;
+gap> L:=AllPrimitiveGroups(NrMovedPoints,n,Size,604800*2);
+[ J_2.2 ]
+gap> G:=L[1];;
+gap> L:=Filtered(GeneralizedOrbitalGraphs(G),x->VertexDegrees(x)=[135]);;
+gap> Length(L);
+1
+gap> gamma:=L[1];; 
+gap> omega:=CliqueNumber(gamma); 
+28
+gap> H:=SylowSubgroup(G,7);;
+gap> blocks:=CompleteSubgraphsOfGivenSize(ComplementGraph(gamma),n/omega,2);
+[ [ 1, 2, 3, 28, 108, 119, 155, 198, 216, 226 ], 
+  [ 1, 2, 3, 118, 119, 140, 193, 213, 218, 226 ] ]
+gap> partition:=GRAPE_ExactSetCover(G,blocks,n,H);; 
+gap> Length(partition);
+28
+gap> colouring:=List([1..n],
+>    x->First([1..Length(partition)],y->x in partition[y]));;
+gap> IsVertexColouring(gamma,colouring,omega);
+true
+\endexample
+

doc/colour.tex

@@ -68,6 +68,31 @@
 fail
 \endexample
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\Section{IsVertexColouring}
+
+\>IsVertexColouring( <gamma>, <C> )
+\>IsVertexColouring( <gamma>, <C>, <k> )
+
+Suppose that <gamma> is a simple graph, <C> is a list of positive integers
+of length `OrderGraph(<gamma>)', and <k> is a non-negative integer
+(default: `OrderGraph(<gamma>)').
+
+Then this function returns `true' if <C> is a vertex <k>-colouring of
+<gamma>, that is, a proper vertex-colouring using at most <k>-colours (for
+which $<C>[i]$ is the colour of the $i$-th vertex), and `false' if not.
+
+\beginexample
+gap> gamma:=JohnsonGraph(7,3);;
+gap> C:=VertexColouring(gamma,6);
+[ 1, 2, 3, 4, 5, 5, 6, 2, 4, 1, 6, 3, 5, 2, 1, 3, 4, 5, 2, 5, 1, 4, 2, 1, 3, 
+  2, 4, 1, 1, 3, 6, 3, 6, 2, 4 ]
+gap> IsVertexColouring(gamma,C);
+true
+gap> IsVertexColouring(gamma,C,5);
+false
+\endexample
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \Section{MinimumVertexColouring}
 

doc/manual.example-10.tst

@@ -7,3 +7,33 @@ gap> Size(G);
 gap> S:=[67,93,100,204,677];;
 gap> SmallestImageSet(G,S);
 [ 1, 2, 22, 220, 453 ]
+gap> n:=10;;
+gap> G:=PSL(2,5);
+Group([ (3,5)(4,6), (1,2,5)(3,4,6) ])
+gap> GRAPE_ExactSetCover(G,[[1,2,3]],6);
+fail
+gap> G:=PGL(2,5);
+Group([ (3,6,5,4), (1,2,5)(3,4,6) ])
+gap> GRAPE_ExactSetCover(G,[[1,2,3]],6);
+[ [ 1, 2, 3 ], [ 4, 5, 6 ] ]
+gap> n:=280;;
+gap> L:=AllPrimitiveGroups(NrMovedPoints,n,Size,604800*2);
+[ J_2.2 ]
+gap> G:=L[1];;
+gap> L:=Filtered(GeneralizedOrbitalGraphs(G),x->VertexDegrees(x)=[135]);;
+gap> Length(L);
+1
+gap> gamma:=L[1];;
+gap> omega:=CliqueNumber(gamma);
+28
+gap> H:=SylowSubgroup(G,7);;
+gap> blocks:=CompleteSubgraphsOfGivenSize(ComplementGraph(gamma),n/omega,2);
+[ [ 1, 2, 3, 28, 108, 119, 155, 198, 216, 226 ],
+  [ 1, 2, 3, 118, 119, 140, 193, 213, 218, 226 ] ]
+gap> partition:=GRAPE_ExactSetCover(G,blocks,n,H);;
+gap> Length(partition);
+28
+gap> colouring:=List([1..n],
+>    x->First([1..Length(partition)],y->x in partition[y]));;
+gap> IsVertexColouring(gamma,colouring,omega);
+true

doc/manual.example-7.tst

@@ -11,6 +11,14 @@ gap> VertexColouring(J,5);
 [ 1, 2, 3, 4, 5, 4, 2, 1, 3, 5 ]
 gap> VertexColouring(J,4);
 fail
+gap> gamma:=JohnsonGraph(7,3);;
+gap> C:=VertexColouring(gamma,6);
+[ 1, 2, 3, 4, 5, 5, 6, 2, 4, 1, 6, 3, 5, 2, 1, 3, 4, 5, 2, 5, 1, 4, 2, 1, 3,
+  2, 4, 1, 1, 3, 6, 3, 6, 2, 4 ]
+gap> IsVertexColouring(gamma,C);
+true
+gap> IsVertexColouring(gamma,C,5);
+false
 gap> J:=JohnsonGraph(5,2);
 rec( adjacencies := [ [ 2, 3, 4, 5, 6, 7 ] ], group := Group([ (1,5,8,10,4)
   (2,6,9,3,7), (2,5)(3,6)(4,7) ]), isGraph := true, isSimple := true,

doc/manual.tex

@@ -71,7 +71,7 @@
 \Input{colour}
 \Input{cnauty}
 \Input{partlin}
-\Input{smallestim}
+\Input{auxil}
 %
 %
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%