% generated by GAPDoc2LaTeX from XML source (Frank Luebeck)
\documentclass[a4paper,11pt]{report}
\usepackage{a4wide}
\sloppy
\pagestyle{myheadings}
\usepackage{amssymb}
\usepackage[latin1]{inputenc}
\usepackage{makeidx}
\makeindex
\usepackage{color}
\definecolor{DarkOlive}{rgb}{0.1047,0.2412,0.0064}
\definecolor{FireBrick}{rgb}{0.5812,0.0074,0.0083}
\definecolor{RoyalBlue}{rgb}{0.0236,0.0894,0.6179}
\definecolor{RoyalGreen}{rgb}{0.0236,0.6179,0.0894}
\definecolor{RoyalRed}{rgb}{0.6179,0.0236,0.0894}
\definecolor{LightBlue}{rgb}{0.8544,0.9511,1.0000}
\definecolor{Black}{rgb}{0.0,0.0,0.0}
\definecolor{FuncColor}{rgb}{1.0,0.0,0.0}
%% strange name because of pdflatex bug:
\definecolor{Chapter }{rgb}{0.0,0.0,1.0}

\usepackage{fancyvrb}

\usepackage{pslatex}

\usepackage[pdftex=true,
        a4paper=true,bookmarks=false,pdftitle={Written with GAPDoc},
        pdfcreator={LaTeX with hyperref package / GAPDoc},
        colorlinks=true,backref=page,breaklinks=true,linkcolor=RoyalBlue,
        citecolor=RoyalGreen,filecolor=RoyalRed,
        urlcolor=RoyalRed,pagecolor=RoyalBlue]{hyperref}

% write page numbers to a .pnr log file for online help
\newwrite\pagenrlog
\immediate\openout\pagenrlog =\jobname.pnr
\immediate\write\pagenrlog{PAGENRS := [}
\newcommand{\logpage}[1]{\protect\write\pagenrlog{#1, \thepage,}}
%% were never documented, give conflicts with some additional packages


\newcommand{\GAP}{\textsf{GAP}}

\begin{document}

\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\begin{center}{\Huge \textbf{GAP 4 Package \textsf{genss}\mbox{}}}\\[1cm]
\hypersetup{pdftitle=GAP 4 Package \textsf{genss}}
\markright{\scriptsize \mbox{}\hfill GAP 4 Package \textsf{genss} \hfill\mbox{}}
{\Large \textbf{generic Schreier-Sims \mbox{}}}\\[1cm]
{ 1.3 \mbox{}}\\[1cm]
{September 2009\mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\large \textbf{Max Neunh{\"o}ffer    \mbox{}}}\\
{\large \textbf{Felix Noeske    \mbox{}}}\\
\hypersetup{pdfauthor=Max Neunh{\"o}ffer    ; Felix Noeske    }
\end{center}\vfill

\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{Max Neunh{\"o}ffer    } --- Email: \href{mailto://neunhoef@mcs.st-and.ac.uk} {\texttt{neunhoef@mcs.st-and.ac.uk}}\\
 --- Homepage: \href{http://www-groups.mcs.st-and.ac.uk/~neunhoef} {\texttt{http://www-groups.mcs.st-and.ac.uk/\texttt{\symbol{126}}neunhoef}}\\
 --- Address: \begin{minipage}[t]{8cm}\noindent
 School of Mathematics and Statistics Mathematical Institute University of St
Andrews North Haugh St Andrews, Fife KY16 9SS Scotland, UK \end{minipage}
}\\
{\mbox{}\\
\small \noindent \textbf{Felix Noeske    } --- Email: \href{mailto://felix.noeske@math.rwth-aachen.de} {\texttt{felix.noeske@math.rwth-aachen.de}}\\
 --- Homepage: \href{http://www.math.rwth-aachen.de/~Felix.Noeske} {\texttt{http://www.math.rwth-aachen.de/\texttt{\symbol{126}}Felix.Noeske}}\\
 --- Address: \begin{minipage}[t]{8cm}\noindent
 Lehrstuhl D f{\"u}r Mathematik, RWTH Aachen, Templergraben 64, 52062 Aachen,
Germany \end{minipage}
}\\
\end{titlepage}

\newpage\setcounter{page}{2}
{\small 
\section*{Copyright}
\logpage{[ 0, 0, 1 ]}
 {\copyright} 2006-2009 by Max Neunh{\"o}ffer and Felix Noeske

 This package may be distributed under the terms and conditions of the GNU
Public License Version 3 or higher. \mbox{}}\\[1cm]
\newpage

\def\contentsname{Contents\logpage{[ 0, 0, 2 ]}}

\tableofcontents
\newpage

  
\chapter{\textcolor{Chapter }{Introduction}}\label{intro}
\logpage{[ 1, 0, 0 ]}
\hyperdef{L}{X7DFB63A97E67C0A1}{}
{
  
\section{\textcolor{Chapter }{Philosophy}}\label{philosophy}
\logpage{[ 1, 1, 0 ]}
\hyperdef{L}{X873C99678745ABAF}{}
{
  This package is about the Schreier-Sims algorithm and base and strong
generating sets for arbitrary finite groups. }

 
\section{\textcolor{Chapter }{Overview over this manual}}\label{overview}
\logpage{[ 1, 2, 0 ]}
\hyperdef{L}{X786BACDB82918A65}{}
{
  Chapter \ref{install} describes the installation of this package. Chapter \ref{StabChains} desribes the core functionality of the package, namely the computation and
usage of stabiliser chains. Chapter \ref{Backtrack} describes some methods using backtrack search. This part of the package is not
yet fully developed and is subject to change in later versions. Finally,
Chapter \ref{examples} shows instructive examples for the usage of this package. As of now, the
number of shown examples is zero. }

  }

  
\chapter{\textcolor{Chapter }{Installation of the \textsf{genss}-Package}}\label{install}
\logpage{[ 2, 0, 0 ]}
\hyperdef{L}{X79F0226A86DDABC3}{}
{
  \index{\textsf{genss}} To install this package just extract the package's archive file to the GAP \texttt{pkg} directory.

 By default the \textsf{genss} package is not automatically loaded by \textsf{GAP} when it is installed. You must load the package with \texttt{LoadPackage("genss");} before its functions become available.

 Please, send us an e-mail if you have any questions, remarks, suggestions,
etc. concerning this package. Also, I would like to hear about applications of
this package.

 Max Neunh{\"o}ffer and Felix Noeske

  }

  
\chapter{\textcolor{Chapter }{Stabiliser Chains}}\label{StabChains}
\logpage{[ 3, 0, 0 ]}
\hyperdef{L}{X8064DE868377020F}{}
{
  This chapter describes the core functionality of the package. It mainly covers
how to use \textsf{genss} to compute stabiliser chains for \textsf{GAP} groups and use them to do sifting. 
\section{\textcolor{Chapter }{Computing stabiliser chains}}\label{StabChainComp}
\logpage{[ 3, 1, 0 ]}
\hyperdef{L}{X7B480F377A18AD40}{}
{
  The main tool to compute a stabiliser chain is the following operation. It has
many options and can be customised in a very flexible way. 

\subsection{\textcolor{Chapter }{StabilizerChain}}
\logpage{[ 3, 1, 1 ]}\nobreak
\hyperdef{L}{X80747C9A7FEB36BE}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StabilizerChain({\slshape G[, opt]})\index{StabilizerChain@\texttt{StabilizerChain}}
\label{StabilizerChain}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a stabiliser chain object or \texttt{fail}



 This operation computes a stabiliser chain for the group \mbox{\texttt{\slshape G}} using a randomised Schreier-Sims algorithm. The second argument \mbox{\texttt{\slshape opt}} is an optional options record. See Section \ref{StabChainOpts} below for an explanation of the possible components. 

 Note that this is a Monte Carlo algorithm in most cases, so there is a small
error probability. However, the only error possible is that some of the
subgroups in the stabiliser chain are proper subgroups of the actual point
stabilisers. So the resulting group order is always a divisor of the actual
group order and if the two are equal, then the stabiliser chain is proved to
be correct. In particular, if the group object \mbox{\texttt{\slshape G}} for some reason already knows the group order, then this procedure always
returns a correct and proven stabiliser chain for \mbox{\texttt{\slshape G}}. }

 }

 
\section{\textcolor{Chapter }{Options for the computation of stabiliser chains}}\label{StabChainOpts}
\logpage{[ 3, 2, 0 ]}
\hyperdef{L}{X784758907BD66D57}{}
{
  The options record for the \texttt{StabilizerChain} (\ref{StabilizerChain}) can contain the following components, which are used to control the behaviour
of the computation of a stabiliser chain for the group \mbox{\texttt{\slshape G}}. Note that for most of these components there are default values to be found
in the global \texttt{GENSS} record. You can change these defaults there if you want but you should know
what you are doing. An explicitly given value in the options record always
takes precedence over the default value. 
\begin{description}
\item[{\texttt{Base}}] This component can either be bound to an existing stabilizer chain object or
to a list of points. In both cases this indicates that the base of the
stabilizer chain or the list of points respectively are known to be a base for
the group \mbox{\texttt{\slshape G}}. In the first case the corresponding action functions are taken from the
stabiliser chain, in the second case one should usually bind the component \texttt{BaseOps} to a list of equal length containing the action functions corresponding to the
base points. 
\item[{\texttt{BaseOps}}] If the \texttt{Base} component is bound to a list of points the \texttt{BaseOps} component must be a list of equal length containing the corresponding action
functions. If the \texttt{BaseOps} component is unbound, a list with identical entries \texttt{OnLines} is used in projective mode and \texttt{OnPoints} in non-projective mode (see component \texttt{Projective} below). 
\item[{\texttt{Cand}}] The \texttt{Cand} component can be bound to a record \texttt{r}which contains candidates for base points in the following way. The \texttt{r.points} component contains the list of points, the \texttt{r.ops} component contains a list of equal length with the corresponding action
functions. The points and actions specified in the \texttt{Cand} component are tried as possible base points for \mbox{\texttt{\slshape G}} (and its stabilisers) first before other points are guessed (see \texttt{FindBasePointCandidates} (\ref{FindBasePointCandidates})). If a point is fixed under all generators it is not used, unless the
component \texttt{Reduced} is explicitly set to \texttt{false} (see below). If the component \texttt{StrictlyUseCandidates} is \texttt{false} (the default, see below), the algorithm tries to use other points of an
already found orbit before considering the next candidate specified by \texttt{Cand}. This is usually sensible because for an already enumerated orbit we have a
natural bound on the length of the suborbits for the point stabiliser in this
orbit. 
\item[{\texttt{DeterministicVerification}}]  Set this component to \texttt{true} to switch on a deterministic verification routine after the randomised
Schreier-Sims procedure. This is not yet implemented. 
\item[{\texttt{ErrorBound}}]  Set this component to a rational number between 0 and 1. It will be an upper
bound for the error probability. That is, the error probability of the Monte
Carlo verification at the end will be less than this rational number. This
component overrides everything you specify in the \texttt{random} or \texttt{VerifyElements} components. 
\item[{\texttt{FailInsteadOfError}}]  If no short enough orbit is found during the computation, the procedure stops
with an error message. If you would rather like it to return \texttt{fail} then set this component to \texttt{true}. This option can be used to try an stabiliser chain computation automatically
and give up before you run out of memory. 
\item[{\texttt{ImmediateVerificationElements}}] Whenever the randomised Schreier-Sims procedure has first computed generators
for a stabiliser in the chain and has computed a stabiliser chain for that
stabiliser recursively, an immediate verification is done. This is to spot
early on that the group found is in fact a proper subgroup of the stabiliser.
This verification is done by creating a few more random elements of that
stabiliser and sifting them through the newly created stabiliser chain. Each
such element has a chance of at least $1/2$ to spot this. The number of random elements used is stored in the component \texttt{ImmediateVerificationElements}. 
\item[{\texttt{InitialHashSize}}]  Set this component to the initial tree hash size for orbit computations in the
stabiliser chain. 
\item[{\texttt{IsOne}}]  The default for this computation is the \texttt{IsOne} (\textbf{Reference: IsOne}) operation in the \textsf{GAP} library. Whenever in the stabiliser chain computation it has to be tested
whether or not a group element is equal to the identity, the function stored
in the \texttt{IsOne} component is called. The rationale behind this is that you can compute a
stabiliser chain for a factor group of the group object \mbox{\texttt{\slshape G}}. For example, if you set the \texttt{IsOne} component to \texttt{GENSS{\textunderscore}IsOneProjective} (\ref{GENSSIsOneProjective}) for a matrix group \mbox{\texttt{\slshape G}}, scalar multiples of the identity are considered to be equal to the identity.
You will have to specify the base points explicitly using the \texttt{Cand} and \texttt{StrictlyUseCandidates} component (see above and below) to only use actions having the normal subgroup
in its kernel. A shortcut for computing stabiliser chains of projective groups
(matrix group modulo scalars) is to set the \texttt{Projective} component (see below) and switch to projective mode. 
\item[{\texttt{LimitShortOrbCandidates}}]  The integer value of this component limits the number of candidates considered
for the finding of short orbits. See the \texttt{TryShortOrbit} and \texttt{TryBirthdayParadox} components. 
\item[{\texttt{NrRandElsBirthdayParadox}}]  The method using the birthday paradox to find short orbits uses at most as
many random group elements to estimate the orbit size as this component says.
See the \texttt{TryBirthdayParadox} component. 
\item[{\texttt{NumberPrevOrbitPoints}}]  After an orbit for the stabiliser chain has been enumerated, the randomised
Schreier-Sims method first tries \texttt{NumberPrevOrbitPoints} from this orbit as next base points. Note that this is not done if the \texttt{StrictlyUseCandidates} component is set to \texttt{true}. 
\item[{\texttt{OrbitLengthLimit}}] This component is an absolute upper bound for the length of all orbits in the
stabiliser chain. If an orbit enumeration reaches this limit, the stabiliser
chain computation is aborted. 
\item[{\texttt{OrbitLimitBirthdayParadox}}]  During the method to find short orbits using the birthday paradox (see
component \texttt{TryBirthdayParadox}) only orbits whose final estimated length is less than \texttt{OrbitLimitBirthdayParadox} are used. 
\item[{\texttt{OrbitLimitImmediatelyTake}}]  During the method to find short orbits using the birthday paradox (see
component \texttt{TryBirthdayParadox}) an orbit is immediately used if its currently estimated length is less than \texttt{OrbitLimitImmediatelyTake}, even if the estimate is not yet very reliable. 
\item[{\texttt{Projective}}]  Set this component to \texttt{true} if you want to compute a stabiliser chain for a projective group given as a
matrix group. Elements which are scalar multiples of each other will be
considered to be equal. This is achieved by only considering projective
actions. Note that in this case a known size of the group object cannot be
used, since this size is the order of the matrix group! 
\item[{\texttt{random}}]  The \texttt{random} component is there as a compatibility option. It behaves exactly as for the
stabiliser chain methods in the \textsf{GAP} library. It must be set to a number between $0$ and $1000$ indicating a lower bound for the probability of a correct answer, where the
value $a$ means $a/10$\%. Note that currently $1000$ is not yet implemented since there is no working deterministic verification
routine. 
\item[{\texttt{RandomElmFunc}}]  If this component is bound then it must be bound to a function taking no
arguments and returning uniformly distributed random elements in the group for
which the stabiliser chain is to be computed. All random elements used for the
stabiliser chain will then be created by calling this function. 
\item[{\texttt{RandomStabGens}}]  This component contains the number of random stabiliser elements that are
generated initially to generate a new stabiliser in the chain. 
\item[{\texttt{Reduced}}]  If this component is bound to \texttt{true}, then no orbits of length $1$ are allowed in the stabiliser chain. That is, no points are taken as base
points that are fixed under all generators of the current stabiliser. Set this
component to \texttt{false} to allow for orbits of length $1$, for example if you want the stabiliser chain to run through a prescribed
base. 
\item[{\texttt{Report}}]  The number in the \texttt{Report} component is taken as the \texttt{Report} component in all orbit enumerations. That is, every \texttt{Report} newly found elements in the orbit a message is printed saying how far the
computation has gone. 
\item[{\texttt{ShortOrbitsInitialLimit}}]  See the \texttt{TryShortOrbit} component. 
\item[{\texttt{ShortOrbitsNrRandoms}}]  See the \texttt{TryShortOrbit} component. 
\item[{\texttt{ShortOrbitsOrbLimit}}]  See the \texttt{TryShortOrbit} component. 
\item[{\texttt{Size}}]  If the \texttt{Size} component is set to a positive integer it is taken as the size of the group \mbox{\texttt{\slshape G}}. This information allows to verify the stabiliser chain simply by looking at
its size. If the group object knows its size already (and the \texttt{Projective} component was not set to \texttt{true}), then the stored size of the group is automatically taken into account, such
that one does not have to use this option. 
\item[{\texttt{StabGenAddSlots}}]  The value of the \texttt{StabGenAddSlots} component is directly handed over to the product replacer object which is used
to generate random elements to find stabiliser generators. 
\item[{\texttt{StabGenMaxDepth}}]  The value of the \texttt{StabGenMaxDepth} component is directly handed over to the product replacer object which is used
to generate random elements to find stabiliser generators. 
\item[{\texttt{StabGenScrambleFactor}}]  The value of the \texttt{StabGenScrambleFactor} component is directly handed over to the product replacer object which is used
to generate random elements to find stabiliser generators. 
\item[{\texttt{StabGenScramble}}]  The value of the \texttt{StabGenScramble} component is directly handed over to the product replacer object which is used
to generate random elements to find stabiliser generators. 
\item[{\texttt{StrictlyUseCandidates}}]  If this component is set to \texttt{true} (default is \texttt{false}) then only the given candidate points are taken as possible base points. In
particular, the procedure does not take additional points of the previous
orbit as candidates for base points (see component \texttt{NumberPrevOrbitPoints} ). Use this option in combination to \texttt{Reduced} set to \texttt{false} to enforce a certain known base. 
\item[{\texttt{TryBirthdayParadox}}]  The method to try to find short orbits using the birthday paradox is used up
to \texttt{TryBirthdayParadox} times for each new base point. This method uses the Murray/O'Brien heuristics
to find candidates for short orbits and then uses statistics using the
birthday paradox to estimate the orbit lengths. As soon as a point is found
whose orbit is either estimated to be smaller than \texttt{OrbitLimitBirthdayParadox} with a solid statistical estimate or is estimated to be smaller than \texttt{OrbitLimitImmediatelyTake} with a weak statistical estimate, this point is taken as the next base point. 
\item[{\texttt{TryShortOrbit}}]  The method to try to find short orbits using the standard Murray/O'Brien
heuristics is used up to \texttt{TryShortOrbit} times for each new base point. This method uses the heuristics to find
candicates for short orbits using \texttt{ShortOrbitsNrRandoms} random group elements. It then enumerates all these orbits up to the limit \texttt{ShortOrbitsInitialLimit}. If any of them closes the corresponding candidate is taken as the next base
point. Otherwise half of the points are thrown away and the limit is doubled.
This goes on until either an orbit closes or the limit grows over \texttt{ShortOrbitsOrbLimit}. 
\item[{\texttt{VerifyElements}}]  This component can be used to set it to the number of random elements that are
used in the end to verify the stabiliser chain statistically. Usually the user
specifies the component \texttt{ErrorBound} instead and \texttt{VerifyElements} is then computed automatically from that. However, if no \texttt{ErrorBound} is given, the \texttt{VerifyElements} component takes precedence over the \texttt{random} component. 
\item[{\texttt{VeryShortOrbLimit}}]  The very first method tried to find the next base point is to enumerate the
orbit of the first and the last basis vector and of one random vector up to
the limit \texttt{VeryShortOrbLimit}. If the orbit closes before this limit is reached, the corresponding vector
is immediately taken. 
\end{description}
  

\subsection{\textcolor{Chapter }{GENSS{\textunderscore}IsOneProjective}}
\logpage{[ 3, 2, 1 ]}\nobreak
\hyperdef{L}{X80C443DB7F951958}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GENSS{\textunderscore}IsOneProjective({\slshape x})\index{GENSSIsOneProjective@\texttt{GENSS{\textunderscore}IsOneProjective}}
\label{GENSSIsOneProjective}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
\texttt{true} or \texttt{false}



 This function tests whether or not the matrix \mbox{\texttt{\slshape x}} is a scalar multiple of the identity matrix. This function is useful for
projective action. }

 }

 
\section{\textcolor{Chapter }{How base points are chosen}}\label{ChooseBasePoints}
\logpage{[ 3, 3, 0 ]}
\hyperdef{L}{X7BBF7C748660197B}{}
{
  This section explains some internal details of how base points are chosen
during a stabiliser chain computations. As a user, you can probably safely
skip this section and ignore it altogether. However, in situations where thes
stabiliser chain computation is more difficult (for example if it is difficult
to find short orbits), then it can be helpful to know about these details. 

 Whenever the stabiliser chain computation needs to set up a new layer in the
stabiliser chain it needs a new base point. The first method it tries is to
take a point in the previous orbit one layer up, since for these points we
have a natural upper limit for the orbit length, namely the orbit length in
the layer above. If this does not work (either there is no higher layer or
more than the first \texttt{NumberPrevOrbitPoints} (see stabiliser chain options in Section \ref{StabChainOpts}) in that orbit are fixed by the current group or \texttt{StrictlyUseCandidates} is \texttt{true}), it is checked whether or not there is another known candidate for a base
point. 

 Note that if the user supplies candidates for the base points and operations
(see component \texttt{Cand} in the stabiliser chain options in Section \ref{StabChainOpts}), then it is entirely possible that all base points come from these
candidates and the mechanisms described in this sections are not used at all. 

 However, if the procedure runs out of base points, it needs a way to find new
candidates. This is done using the following operation: 

\subsection{\textcolor{Chapter }{FindBasePointCandidates}}
\logpage{[ 3, 3, 1 ]}\nobreak
\hyperdef{L}{X814A0FEE7B677BF7}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FindBasePointCandidates({\slshape g, opt, i, S})\index{FindBasePointCandidates@\texttt{FindBasePointCandidates}}
\label{FindBasePointCandidates}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a \texttt{Cand} record



 This operation returns base point candidates in the form of a record as for
the \texttt{Cand} option for stabiliser chain computations (see Section \ref{StabChainOpts}). }

 There are various methods installed to this end which all might fail and call \texttt{TryNextMethod();}. We do not document the details of these methods here but only give an
overview. For permutation groups the choice of candidates is very
straightforward, one simply takes a few integers with the usual action \texttt{OnPoints}. For matrix group finding a reasonably short orbit is more difficult. The
system first handles the case of a scalar group which is easy. Then it hopes
to find a ``very short orbit'' defined by the component \texttt{VeryShortOrbLimit} in the stabiliser chain computation options. If this fails the birthday
paradoxon method is used to find an estimate for a reasonably short orbit
amoung candidates coming from the Murray and O'Brien heuristics. If this fails
the same heuristics are used but various orbits are enumerated up to a certain
point decreasing the number of orbits as the limit goes up. If all fails some
of the candidates from the heuristics are simply tried with brute force. The
whole computation can fail if some upper orbit length limit is reached (see
component \texttt{OrbitLengthLimit} in the stabiliser chain computation options). }

 
\section{\textcolor{Chapter }{Using stabiliser chains}}\label{UseStabChain}
\logpage{[ 3, 4, 0 ]}
\hyperdef{L}{X7F17287C81771245}{}
{
  The most important thing one can do with a stabiliser chain is sifting. This
is done with one of the next to operations: 

\subsection{\textcolor{Chapter }{SiftGroupElement}}
\logpage{[ 3, 4, 1 ]}\nobreak
\hyperdef{L}{X7BAA7E4478F5CFA9}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SiftGroupElement({\slshape S, el})\index{SiftGroupElement@\texttt{SiftGroupElement}}
\label{SiftGroupElement}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a record



 The first argument \mbox{\texttt{\slshape S}} must be a stabiliser chain object and the second argument \mbox{\texttt{\slshape el}} a group element (not necessarily contained in the group described by \mbox{\texttt{\slshape S}}). The result is a record describing the result of the sifting process. The
component \texttt{rem} contains the remainder of the sifting process. If \mbox{\texttt{\slshape el}} is contained in the group described by \mbox{\texttt{\slshape S}}, then the remainder is equal to the identity. Note that if the \texttt{IsOne}-component of the options record for the stabiliser chain \mbox{\texttt{\slshape S}} is different from the \texttt{IsOne} (\textbf{Reference: IsOne}) operation then the \texttt{rem} component is equal to the identity according to that test. The result of this
test (\texttt{true} or \texttt{false}) is stored in the component \texttt{isone} of the resulting record. This means, that this component indicates whether or
not the sifting was successful. The component \texttt{S} is bound to the stabiliser chain object corresponding to the layer in which
the sifting stopped. If it ran through the whole chain this component is bound
to \texttt{false}. The component \texttt{preS} is always bound to the previous layer, which is the lowest layer if the
sifting was successful. }

 

\subsection{\textcolor{Chapter }{SiftGroupElementSLP}}
\logpage{[ 3, 4, 2 ]}\nobreak
\hyperdef{L}{X7C88F18C79DF9005}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SiftGroupElementSLP({\slshape S, el})\index{SiftGroupElementSLP@\texttt{SiftGroupElementSLP}}
\label{SiftGroupElementSLP}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a record



 This operation behaves exactly as \texttt{SiftGroupElement} (\ref{SiftGroupElement}) except that in the successful case the component \texttt{slp} of the resulting record is additionally bound to a straight line program which
expresses the element \mbox{\texttt{\slshape el}} in terms of the strong generators of the stabiliser chain (see \texttt{StrongGenerators} (\ref{StrongGenerators})). }

 

\subsection{\textcolor{Chapter }{StrongGenerators}}
\logpage{[ 3, 4, 3 ]}\nobreak
\hyperdef{L}{X82EFC40987B17368}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StrongGenerators({\slshape S})\index{StrongGenerators@\texttt{StrongGenerators}}
\label{StrongGenerators}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a list of group elements



 This operation returns the strong generators of the stabiliser chain \mbox{\texttt{\slshape S}}. This means that each stabiliser in the stabiliser chain is generated by the
subset of the set of strong generators which fix the corresponding points.
Note that each layer of the stabiliser chain uses some subset of these strong
generators as generators for the orbit object of that layer. }

 

\subsection{\textcolor{Chapter }{NrStrongGenerators}}
\logpage{[ 3, 4, 4 ]}\nobreak
\hyperdef{L}{X7FC7256285A2110A}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{NrStrongGenerators({\slshape S})\index{NrStrongGenerators@\texttt{NrStrongGenerators}}
\label{NrStrongGenerators}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a positive integer



 This operation returns the number of strong generators of the stabiliser chain \mbox{\texttt{\slshape S}} (see \texttt{StrongGenerators} (\ref{StrongGenerators})). }

 

\subsection{\textcolor{Chapter }{BaseStabilizerChain}}
\logpage{[ 3, 4, 5 ]}\nobreak
\hyperdef{L}{X7956F37981FD2F48}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{BaseStabilizerChain({\slshape S})\index{BaseStabilizerChain@\texttt{BaseStabilizerChain}}
\label{BaseStabilizerChain}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a record



 This operation returns the base of the stabiliser chain \mbox{\texttt{\slshape S}} in form of a record, which can be used as the \texttt{Cand} component for a stabiliser chain computation. That is, two components are
bound, the \texttt{points} component is a list of base points and the \texttt{ops} component is a corresponding list of action functions. }

 

\subsection{\textcolor{Chapter }{Size}}
\logpage{[ 3, 4, 6 ]}\nobreak
\hyperdef{L}{X858ADA3B7A684421}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Size({\slshape S})\index{Size@\texttt{Size}}
\label{Size}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a positive integer



 This operation returns the size (i.e. order) of the group described by the
stabiliser chain \mbox{\texttt{\slshape S}}. This is simply the product of the lengths of the orbits in the chain. }

 

\subsection{\textcolor{Chapter }{Random}}
\logpage{[ 3, 4, 7 ]}\nobreak
\hyperdef{L}{X79730D657AB219DB}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Random({\slshape S})\index{Random@\texttt{Random}}
\label{Random}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a group element



 This operation can be called with a stabiliser chain object \mbox{\texttt{\slshape S}} or with a group object, if this group object has a stored stabiliser chain
(see \texttt{SetStabilizerChain} (\ref{SetStabilizerChain})). The method will randomly choose transversal elements and thus produce a
uniformly distributed random element of the group. }

 

\subsection{\textcolor{Chapter }{\texttt{\symbol{92}}in}}
\logpage{[ 3, 4, 8 ]}\nobreak
\hyperdef{L}{X87BDB89B7AAFE8AD}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{\texttt{\symbol{92}}in({\slshape x, S})\index{in@\texttt{\texttt{\symbol{92}}in}}
\label{in}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
\texttt{true} or \texttt{false}



 This operation tests whether or not the group element \mbox{\texttt{\slshape x}} lies in the group described by the stabiliser chain \mbox{\texttt{\slshape S}} by sifting (see \texttt{SiftGroupElement} (\ref{SiftGroupElement})). The argument \mbox{\texttt{\slshape S}} can also be a group object with a stored stabiliser chain (see \texttt{SetStabilizerChain} (\ref{SetStabilizerChain})). Note that this operation can be called with the \texttt{in} keyword using infix notation. }

 

\subsection{\textcolor{Chapter }{IsProved}}
\logpage{[ 3, 4, 9 ]}\nobreak
\hyperdef{L}{X84103D1A854F6E73}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsProved({\slshape S})\index{IsProved@\texttt{IsProved}}
\label{IsProved}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
\texttt{true} or \texttt{false}



 This operation returns whether or not the stabiliser chain \mbox{\texttt{\slshape S}} is proved to be correct. If it has only been verified by randomised methods, \texttt{false} is returned. At the time of this writing the only possible deterministic
verification is if the size of the group is known before the stabiliser chain
computation begins. }

 

\subsection{\textcolor{Chapter }{GroupIteratorByStabilizerChain}}
\logpage{[ 3, 4, 10 ]}\nobreak
\hyperdef{L}{X837389DA857F0596}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GroupIteratorByStabilizerChain({\slshape S})\index{GroupIteratorByStabilizerChain@\texttt{GroupIteratorByStabilizerChain}}
\label{GroupIteratorByStabilizerChain}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
an iterator



 This operation returns an iterator object which runs through the elements of
the group described by the stabiliser chain object \mbox{\texttt{\slshape S}}. The usual operations \texttt{NextIterator} (\textbf{Reference: NextIterator}) and \texttt{IsDoneIterator} (\textbf{Reference: IsDoneIterator}) as well as the \texttt{for} loop construction can be used with this object. The iterator is implemented
using the stored transversals in the Schreier trees of the stabiliser chain. }

 

\subsection{\textcolor{Chapter }{SetStabilizerChain}}
\logpage{[ 3, 4, 11 ]}\nobreak
\hyperdef{L}{X8639DF037FAB2E96}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SetStabilizerChain({\slshape g, S})\index{SetStabilizerChain@\texttt{SetStabilizerChain}}
\label{SetStabilizerChain}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
nothing



 Once the user is convinced that the stabiliser chain \mbox{\texttt{\slshape S}} describes the group \mbox{\texttt{\slshape g}} correctly, he can call this operation to store the stabiliser chain together
with the group object. From then on, additional methods using the stabiliser
chain (for example \texttt{Size} (\ref{Size}), \texttt{Random} (\ref{Random}) and \texttt{\texttt{\symbol{92}}in} (\ref{in}) above) become applicable for the group object. Note that if a stabiliser chain
is known to be correct (for example if the group knew its size beforehand),
then the stabiliser chain is stored with the group automatically when it is
constructed, which makes the explicit storing of the stabiliser chain
unnecessary. 

 The stored stabiliser chain of a group object can be used using \texttt{StoredStabilizerChain} (\ref{StoredStabilizerChain}). }

 

\subsection{\textcolor{Chapter }{StoredStabilizerChain}}
\logpage{[ 3, 4, 12 ]}\nobreak
\hyperdef{L}{X7C12BF8B7976B1FC}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StoredStabilizerChain({\slshape g})\index{StoredStabilizerChain@\texttt{StoredStabilizerChain}}
\label{StoredStabilizerChain}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
a stabiliser chain



 This attribute for a group object \mbox{\texttt{\slshape g}} contains a stored stabiliser chain for the group. See \texttt{SetStabilizerChain} (\ref{SetStabilizerChain}) for details. }

 

\subsection{\textcolor{Chapter }{StabChainOp}}
\logpage{[ 3, 4, 13 ]}\nobreak
\hyperdef{L}{X7B0B01C4875F2CB8}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StabChainOp({\slshape p, S})\index{StabChainOp@\texttt{StabChainOp}}
\label{StabChainOp}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
a \textsf{GAP} stabiliser chain 



 This method computes a standard \textsf{GAP} library stabiliser chain for the permutation group \mbox{\texttt{\slshape p}} using the fact that \mbox{\texttt{\slshape S}} is a known correct stabiliser chain for \mbox{\texttt{\slshape p}}. If all base points in \mbox{\texttt{\slshape S}} are positive integers and all actions are equal to \texttt{OnPoints}, then the same base points are taken for the new stabiliser chain. }

 

\subsection{\textcolor{Chapter }{SiftBaseImage}}
\logpage{[ 3, 4, 14 ]}\nobreak
\hyperdef{L}{X7952DA8183229C8C}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SiftBaseImage({\slshape S, l})\index{SiftBaseImage@\texttt{SiftBaseImage}}
\label{SiftBaseImage}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
\texttt{true} or \texttt{false}



 This operation sifts an image \mbox{\texttt{\slshape l}} of the base points of the stabiliser chain \mbox{\texttt{\slshape S}}. This means that the elements of the list \mbox{\texttt{\slshape l}} must be images of the base points under the actions in the various layers of
the stabiliser chain. The sifting procedure using the orbits and Schreier
trees in the stabiliser chain decides if this base image is one for a group
element of the group described by \mbox{\texttt{\slshape S}} and returns \texttt{true} or \texttt{false} accordingly. 

 This operation is mostly used internally. }

 

\subsection{\textcolor{Chapter }{SLPChainStabilizerChain}}
\logpage{[ 3, 4, 15 ]}\nobreak
\hyperdef{L}{X7DB069EA7A77DD4D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SLPChainStabilizerChain({\slshape S, gens})\index{SLPChainStabilizerChain@\texttt{SLPChainStabilizerChain}}
\label{SLPChainStabilizerChain}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a record



 This operation assumes that \mbox{\texttt{\slshape S}} is a stabiliser chain that correctly describes the group generated by the
generators \mbox{\texttt{\slshape gens}}. It returns a list of straight line programs expressing successively the
stabilisers in the chain, each in terms of the generators of the previous, the
first in terms of \mbox{\texttt{\slshape gens}}. This list is stored in the component \texttt{slps} of the resulting record. The sizes of the groups in the chain are stored in
the component \texttt{sizes} of the resulting record. }

 The operations, functions and methods described below use stabiliser chains
internally: 

\subsection{\textcolor{Chapter }{GroupHomomorphismByImagesNCStabilizerChain}}
\logpage{[ 3, 4, 16 ]}\nobreak
\hyperdef{L}{X7DE1ACFA81002A5E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GroupHomomorphismByImagesNCStabilizerChain({\slshape g, h, images, opt1, opt2})\index{GroupHomomorphismByImagesNCStabilizerChain@\texttt{Group}\-\texttt{Homomorphism}\-\texttt{By}\-\texttt{Images}\-\texttt{N}\-\texttt{C}\-\texttt{Stabilizer}\-\texttt{Chain}}
\label{GroupHomomorphismByImagesNCStabilizerChain}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a group homomorphism



 This function creates a group homomorphism object from the group \mbox{\texttt{\slshape g}} into the group object \mbox{\texttt{\slshape h}}, mapping the generators of the group \mbox{\texttt{\slshape g}} to the elements \mbox{\texttt{\slshape images}} which must lie in \mbox{\texttt{\slshape h}}. This mapping must be a group homomorphism, note that this is not checked! 

 The homomorphism is computed by computing stabiliser chains on both sides such
that elements can be mapped in both directions simply be sifting and
expressing them in terms of the strong generators. This is where the two
arguments \mbox{\texttt{\slshape opts1}} and \mbox{\texttt{\slshape opts2}} come into play. The former is used as the options record for the stabiliser
computation in \mbox{\texttt{\slshape g}} and the latter for the one in the group generated by \mbox{\texttt{\slshape images}}. }

 

\subsection{\textcolor{Chapter }{FindShortGeneratorsOfSubgroup}}
\logpage{[ 3, 4, 17 ]}\nobreak
\hyperdef{L}{X80BB35D380A972BB}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FindShortGeneratorsOfSubgroup({\slshape g, u})\index{FindShortGeneratorsOfSubgroup@\texttt{FindShortGeneratorsOfSubgroup}}
\label{FindShortGeneratorsOfSubgroup}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
a record



 This is an additional method for matrix or permutation groups implementing the
operation \texttt{FindShortGeneratorsOfSubgroup} from the \textsf{orb} package using stabiliser chains. Both arguments must be groups and \mbox{\texttt{\slshape u}} must be a subgroup of \mbox{\texttt{\slshape g}}. The resulting record contains two components \texttt{gens} and \texttt{slp}, where the first is a list of generators for the group \mbox{\texttt{\slshape u}} and the second is a straight line program expressing \texttt{gens} in terms of the generators of \mbox{\texttt{\slshape g}}. This operation aims to find short words in the generators of \mbox{\texttt{\slshape g}} to use as generators for \mbox{\texttt{\slshape u}}. }

 

\subsection{\textcolor{Chapter }{Stab}}
\logpage{[ 3, 4, 18 ]}\nobreak
\hyperdef{L}{X87B01CDA7D44C5A2}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Stab({\slshape g, x, op[, opt]})\index{Stab@\texttt{Stab}}
\label{Stab}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a record or \texttt{fail}



 This operation aims to compute the point stabiliser of the group \mbox{\texttt{\slshape g}} acting via the action function \mbox{\texttt{\slshape op}} of the point \mbox{\texttt{\slshape x}}. The optional last argument is an options record. The general approach of
this procedure is to go back and forth between enumerating a part of the orbit
and trying to produce random elements in the stabiliser using the already
enumerated part of the orbit. Random elements in the stabiliser are produced
by using product replacement in \mbox{\texttt{\slshape g}} to produce random elements of \mbox{\texttt{\slshape g}} and then using the Schreier tree of the orbit to map them back into the
stabiliser. If this works, the resulting random elements are distributed
uniformly in the point stabiliser. 

 This routine is a Monte Carlo procedure. If sufficiently many random elements
of the stabiliser have been produced and did not increase its size, the
program concludes that the whole stabiliser is found and returns a record
describing it. Otherwise it returns \texttt{fail} after some time. 

 The resulting record has the stabiliser in the component \texttt{stab}, its size estimate in the component \texttt{size}, a stabiliser chain for \texttt{stab} in the component \texttt{stabilizerchain} and a boolean value in the component \texttt{proof} indicating whether or not the result is certain. 

 We do not document all possible options in the options record here, since we
want to allow for the possibility to change these in later versions. The most
important component in the options record is the component \texttt{ErrorBound} which must be bound to a rational number between 0 and 1 and which is an upper
bound for the error probability. 

 Please note again that two types of errors can occur in this program: The
first is that the correct point stabiliser is not found but only a proper
subgroup of it. The second is that the stabiliser chain computation to
estimate its size went wrong and returns an incorrect stabiliser chain. }

  }

  }

  
\chapter{\textcolor{Chapter }{Backtrack search methods}}\label{Backtrack}
\logpage{[ 4, 0, 0 ]}
\hyperdef{L}{X7A4E22528475FE10}{}
{
  This chapter describes the methods for backtrack search in the \textsf{genss} package. Note that the code in this area is not yet very stable and is almost
certainly going to change in subsequent versions of this package. This might
also concern the interfaces and calling conventions. 
\section{\textcolor{Chapter }{Setwise stabilisers}}\logpage{[ 4, 1, 0 ]}
\hyperdef{L}{X7D3782CF793C6AEE}{}
{
  

\subsection{\textcolor{Chapter }{SetwiseStabilizer}}
\logpage{[ 4, 1, 1 ]}\nobreak
\hyperdef{L}{X82E47897844105A1}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SetwiseStabilizer({\slshape G, op, M})\index{SetwiseStabilizer@\texttt{SetwiseStabilizer}}
\label{SetwiseStabilizer}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a record



 This operation computes the setwise stabiliser of the set \mbox{\texttt{\slshape M}}. So \mbox{\texttt{\slshape G}} must be a group acting on some set $\Omega$, this action is given by the action function \mbox{\texttt{\slshape op}}. The set \mbox{\texttt{\slshape M}} must consist of elements $\Omega$. The result is a record with the components \texttt{setstab} containing the setwise stabiliser and \texttt{S} containing a stabiliser chain for it. 

 This operation uses backtrack search in a specially crafted stabiliser chain
for \mbox{\texttt{\slshape G}} doing not much intelligent pruning of the search tree, so expect possible long
delays! }

 

\subsection{\textcolor{Chapter }{SetwiseStabilizerPartitionBacktrack}}
\logpage{[ 4, 1, 2 ]}\nobreak
\hyperdef{L}{X80F3D70A80D2B4FD}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SetwiseStabilizerPartitionBacktrack({\slshape G, op, M})\index{SetwiseStabilizerPartitionBacktrack@\texttt{SetwiseStabilizerPartitionBacktrack}}
\label{SetwiseStabilizerPartitionBacktrack}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a record



 This operation computes the setwise stabiliser of the set \mbox{\texttt{\slshape M}}. So \mbox{\texttt{\slshape G}} must be a group acting on some set $\Omega$, this action is given by the action function \mbox{\texttt{\slshape op}}. The set \mbox{\texttt{\slshape M}} must consist of elements $\Omega$. The result is a record with the components \texttt{setstab} containing the setwise stabiliser and \texttt{S} containing a stabiliser chain for it. 

 This operation uses backtrack search in a specially crafted stabiliser chain
for \mbox{\texttt{\slshape G}}. It does some ideas coming from partition backtrack but does not (yet)
implement a full featured partition backtrack, so expect possible longish
delays! }

 }

 
\section{\textcolor{Chapter }{Generic backtrack search}}\logpage{[ 4, 2, 0 ]}
\hyperdef{L}{X80EC4351864EAA8B}{}
{
  

\subsection{\textcolor{Chapter }{BacktrackSearchStabilizerChainElement}}
\logpage{[ 4, 2, 1 ]}\nobreak
\hyperdef{L}{X8400084E83FD7EAF}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{BacktrackSearchStabilizerChainElement({\slshape S, P, g, pruner})\index{BacktrackSearchStabilizerChainElement@\texttt{BacktrackSearchStabilizerChainElement}}
\label{BacktrackSearchStabilizerChainElement}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
\texttt{fail} or a group element



 Let $G$ be the group described by the stabiliser chain \mbox{\texttt{\slshape S}}. The group element \mbox{\texttt{\slshape g}} must be some element in an overgroup $\hat G$of $G$ such that the function \mbox{\texttt{\slshape P}} described below is defined on the whole of $\hat G$ 

 This operation implements a generic backtrack search in the coset $G\mbox{\texttt{\slshape g}}$ looking for an element $x\ in G$ such that \mbox{\texttt{\slshape P}}$(x\mbox{\texttt{\slshape g}})$ is \texttt{true} where \mbox{\texttt{\slshape P}} is a function on $\hat G$taking values \texttt{true} and \texttt{false}. The operation returns the group element $x$ if one is found or \texttt{fail} if none was found. 

 The search tree is given by the stabiliser chain, each node corresponds to a
right coset of one of the stabilisers in the chain. The leaves correspond to
right cosets of the identity group, i.e. to group elements in $G\mbox{\texttt{\slshape g}}$ 

 To make this backtrack search efficient some pruning of the search tree has to
be done. To this end there is the fourth argument \mbox{\texttt{\slshape pruner}} which can either be \texttt{false} (in which case no pruning at all happens) or a \textsf{GAP} function taking 5 arguments and returning either \texttt{true} or \texttt{false}. The function \mbox{\texttt{\slshape pruner}} is called for every node in the search tree before the backtrack search
descents into the subtrees. If the \mbox{\texttt{\slshape pruner}} function returns \texttt{false}, the complete subtree starting at the current node is pruned and no further
search is performed there. If the result is \texttt{true} (or \mbox{\texttt{\slshape pruner}} was equal to \texttt{false} altogether) then the subtree starting at the current node is searched
recursively. Obviously, the \mbox{\texttt{\slshape pruner}} function needs to know the current position in the search tree, which it is
told by its arguments. 

 Each node in the search tree corresponds to a coset of some stabiliser of the
stabiliser chain in its previous one. To set up some notation, let $ G = S_0 > S_1 > S_2 > \cdots > S_m > S_{{m+1}} = \{1\} $ be the stabiliser chain and let $ O_1, O_2, \ldots, O_m $ be the basic orbits. Then for the node corresponding to the coset $S_i t\mbox{\texttt{\slshape g}}$ for $i \ge 1$ and some transversal element $t$ contained in $S_{{i-1}}$ the arguments with which the \mbox{\texttt{\slshape pruner}} function is called are the following: The first argument is the stabiliser
chain object corresponding to $S_{{i-1}}$. The second argument is the index of the element in $O_i$ corresponding to the transversal element $t$. The third argument is the group element $t\mbox{\texttt{\slshape g}}$ and the fourth argument is equal to the actual transversal element $t$. The fifth argument is a word in the generators used to enumerate $O_i$ expressing $t$, the word comes as a list of integers which are the generator numbers. }

 

\subsection{\textcolor{Chapter }{BacktrackSearchStabilizerChainSubgroup}}
\logpage{[ 4, 2, 2 ]}\nobreak
\hyperdef{L}{X7D31CCB08688F4E3}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{BacktrackSearchStabilizerChainSubgroup({\slshape S, P, pruner})\index{BacktrackSearchStabilizerChainSubgroup@\texttt{BacktrackSearchStabilizerChainSubgroup}}
\label{BacktrackSearchStabilizerChainSubgroup}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
\texttt{fail} or a stabiliser chain



 Let $G$ be the group described by the stabiliser chain \mbox{\texttt{\slshape S}}. This operation implements a generic backtrack search in the stabiliser chain \mbox{\texttt{\slshape S}} looking for the subgroup $H$ of the group $G$ described by \mbox{\texttt{\slshape S}} of all elements $x$ for which \mbox{\texttt{\slshape P}}$(x)$ is \texttt{true}, where \mbox{\texttt{\slshape P}} is a function on $G$ taking values \texttt{true} or \texttt{false}. Note that of course \mbox{\texttt{\slshape P}} must be such that $H$ is actually a subgroup! The operation returns a stabiliser chain describing
the group $H$. 

 The search tree is given by the stabiliser chain, each node corresponds to a
right coset of one of the stabilisers in the chain. The leaves correspond to
right cosets of the identity group, i.e. to group elements in $G$ 

 To make this backtrack search efficient some pruning of the search tree has to
be done. To this end there is the fourth argument \mbox{\texttt{\slshape pruner}} which can either be \texttt{false} (in which case no pruning at all happens) or a \textsf{GAP} function taking 5 arguments and returning either \texttt{true} or \texttt{false}. The function \mbox{\texttt{\slshape pruner}} is called for every node in the search tree before the backtrack search
descents into the subtrees. If the \mbox{\texttt{\slshape pruner}} function returns \texttt{false}, the complete subtree starting at the current node is pruned and no further
search is performed there. If the result is \texttt{true} (or \mbox{\texttt{\slshape pruner}} was equal to \texttt{false} altogether) then the subtree starting at the current node is searched
recursively. Obviously, the \mbox{\texttt{\slshape pruner}} function needs to know the current position in the search tree, which it is
told by its arguments. 

 Each node in the search tree corresponds to a coset of some stabiliser of the
stabiliser chain in its previous one. To set up some notation, let $ G = S_0 > S_1 > S_2 > \cdots > S_m > S_{{m+1}} = \{1\} $ be the stabiliser chain and let $ O_1, O_2, \ldots, O_m $ be the basic orbits. Then for the node corresponding to the coset $S_i t\mbox{\texttt{\slshape g}}$ for $i \ge 1$ and some transversal element $t$ contained in $S_{{i-1}}$ the arguments with which the \mbox{\texttt{\slshape pruner}} function is called are the following: The first argument is the stabiliser
chain object corresponding to $S_{{i-1}}$. The second argument is the index of the element in $O_i$ corresponding to the transversal element $t$. The third and fourth arguments are the transversal element $t$. The fifth argument is a word in the generators used to enumerate $O_i$ expressing $t$, the word comes as a list of integers which are the generator numbers. }

 }

  }

  
\chapter{\textcolor{Chapter }{Examples}}\label{examples}
\logpage{[ 5, 0, 0 ]}
\hyperdef{L}{X7A489A5D79DA9E5C}{}
{
  Here comes text.

  }

 \def\bibname{References\logpage{[ "Bib", 0, 0 ]}
\hyperdef{L}{X7A6F98FD85F02BFE}{}
}

\bibliographystyle{alpha}
\bibliography{genss}

\def\indexname{Index\logpage{[ "Ind", 0, 0 ]}
\hyperdef{L}{X83A0356F839C696F}{}
}


\printindex

\newpage
\immediate\write\pagenrlog{["End"], \arabic{page}];}
\immediate\closeout\pagenrlog
\end{document}
