% 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{recogbase}\mbox{}}}\\[1cm]
\hypersetup{pdftitle=GAP 4 Package \textsf{recogbase}}
\markright{\scriptsize \mbox{}\hfill GAP 4 Package \textsf{recogbase} \hfill\mbox{}}
{\Large \textbf{A framework for group recognition\mbox{}}}\\[1cm]
{ 1.0 \mbox{}}\\[1cm]
{November 2009\mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\large \textbf{Max Neunhoeffer    \mbox{}}}\\
{\large \textbf{{\a'A}kos Seress    \mbox{}}}\\
\hypersetup{pdfauthor=Max Neunhoeffer    ; {\a'A}kos Seress    }
\end{center}\vfill

\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{Max Neunhoeffer    } --- 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, North Haugh, St
Andrews, Fife, KY16 9SS, Scotland, UK\end{minipage}
}\\
{\mbox{}\\
\small \noindent \textbf{{\a'A}kos Seress    } --- Email: \href{mailto://akos@math.ohio-state.edu} {\texttt{akos@math.ohio-state.edu}}\\
 --- Homepage: \href{http://www.math.ohio-state.edu/people/display/display.php?ID=302 } {\texttt{http://www.math.ohio-state.edu/people/display/display.php?ID=302 }}\\
 --- Address: \begin{minipage}[t]{8cm}\noindent
 Department of Mathematics, The Ohio State University, 231 W 18th Avenue,
Columbus, OH 43210 USA \end{minipage}
}\\
\end{titlepage}

\newpage\setcounter{page}{2}
{\small 
\section*{Copyright}
\logpage{[ 0, 0, 1 ]}
 {\copyright} 2005-2009 by Max Neunh{\"o}ffer and {\a'A}kos Seress

 This package may be distributed under the terms and conditions of the GNU
Public License Version 3 or (at your option) any later version. \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 group recognition. It provides a generic framework to
implement methods of group recognition, regardless of what computational
representation is used. This means, that the code in this package is useful at
least for permutation groups, matrix groups, projective groups and for the
context of black box groups. The setup is described in \cite{IssacRecog}. 

 The framework allows to build composition trees and handles the builtup and
usage of these trees in a generic way. It also contains a method selection
(described in Chapter \ref{methsel}) that allows install recognition methods in a convenient way and that
automatically tries to try the different available methods in a sensible
order. }

 
\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{recognition} describes the generic, recursive procedure used for group recognition
throughout this package. At the heart of this procedure is the definition of ``FindHomomorphism'' methods, which is also described in that chapter. For the choice of the right
method for finding a homomorphism (or an isomorphism) we use another generic
procedure, the ``method selection'' which is not to be confused with the \textsf{GAP} method selection. Our own method selection is described in detail in Chapter \ref{methsel}, because it is interesting in its own right and might be useful in other
circumstances. Finally, in Chapter \ref{afterrecog} we describe, what one can do with a completed recognition tree. }

  }

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

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

 Usually, this package is only usable if you also install the \textsf{recog} package containing all the implemented recognition methods. Since the \textsf{recog} package then automatically loads the \textsf{recogbase} one only has to load both packages with \texttt{LoadPackage("recog");}.

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

 Max Neunh{\"o}ffer and {\a'A}kos Seress

  }

  
\chapter{\textcolor{Chapter }{Method Selection}}\label{methsel}
\logpage{[ 3, 0, 0 ]}
\hyperdef{L}{X8058CC8187162644}{}
{
  The setup described in this chapter is intended for situations, in which lots
of different methods are available to fulfill a certain task, but in which it
is not possible in the beginning to decide, which one to use. Therefore this
setup regulates, rather than just which method to choose, in which order the
various methods are tried. The methods themselves return whether they were
successful and, if not, whether it is sensible to try them again at a later
stage.

 The design is intentionally kept as simple as possible and at the same time as
versatile as possible, thereby providing a useful framework for many
situations as described above.

 Note the differences to the \textsf{GAP} method selection, which is designed with the idea in mind that it will be
quite clear in most situations, which one is ``the best'' method for a given set of input data, and that we do not want to try different
things. On the other hand, the \textsf{GAP} method selection is quite complicated, which is to some extend necessary to
make sure, that lots of different information about the objects in question
can be used to really find the best method.

 Our setup here in particular has to fulfill the requirement, that in the end,
with lots of methods installed, one still has to be able to have an overview
and to ``prove'', that the whole system always does the right thing.

 
\section{\textcolor{Chapter }{What are methods?}}\label{whataremethods}
\logpage{[ 3, 1, 0 ]}
\hyperdef{L}{X7F89FF55818F1139}{}
{
  A method is just a \textsf{GAP} function together with an agreement about what arguments it takes and what
result it returns. The agreement about the arguments of course has to be made
for every situation in which this generic method selection code is used, and
the user is completely free there. A method can (and has to) return one of the
following four values:

 
\begin{description}
\item[{\texttt{true}}] means that the method was successful and no more methods have to be tried.
\item[{\texttt{false}}] means that the method was not successful and that there is no point to call
the method again in this situation whatsoever.
\item[{\texttt{fail}}] means that the method temporarily failed, that it however could be sensible to
call it again in this situation at a later stage. This value is typical for a
Las Vegas algorithm using randomised methods, which has failed, but which may
succeed when called again.
\item[{\texttt{NotApplicable}}] means that the method for some reason refused to do its work. However, it is
possible that it will become applicable later such that it makes sense to call
it again, may when more information is available.
\end{description}
 For administration in the method selection, a method is described by a record
with the following components bound: 
\begin{description}
\item[{\texttt{method}}] holds the function itself.
\item[{\texttt{rank}}] holds an integer used to sort the various methods. Higher numbers mean that
the method is tried earlier. The numbering scheme is left to the user. 
\item[{\texttt{stamp}}] holds a string value that uniquely describes the method. This is used for
bookkeeping and to keep track of what has to be tried how often. 
\item[{\texttt{comment}}] a string valued comment. This field is optional and can be left out. 
\end{description}
 The different methods for a certain task are collected in so-called ``method databases''. A \emph{method database} is just a list of records, each describing a method in the format described
above. Usually, the ranks will be descending, but that is not necessary.

 There is one convenience function to put a new method into a method database: 

\subsection{\textcolor{Chapter }{AddMethod}}
\logpage{[ 3, 1, 1 ]}\nobreak
\hyperdef{L}{X845DB71C806CADDC}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AddMethod({\slshape db, meth, rank, stamp[, comment]})\index{AddMethod@\texttt{AddMethod}}
\label{AddMethod}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 \mbox{\texttt{\slshape db}} must be a method database (list of records, see above) with non-ascending rank
values. \mbox{\texttt{\slshape meth}} is the method function, \mbox{\texttt{\slshape rank}} the rank and \mbox{\texttt{\slshape stamp}} a string valued stamp. The optional argument \mbox{\texttt{\slshape comment}} can be a string comment. The record describing the method is created and
inserted at the correct position in the method database. Nothing is returned. }

 }

 
\section{\textcolor{Chapter }{How methods are called}}\label{howcalled}
\logpage{[ 3, 2, 0 ]}
\hyperdef{L}{X83FCCBCA78F608E1}{}
{
  Whenever the method selection shall be used, one calls the following function: 

\subsection{\textcolor{Chapter }{CallMethods}}
\logpage{[ 3, 2, 1 ]}\nobreak
\hyperdef{L}{X7BC2692183B6C4E6}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CallMethods({\slshape db, limit[, furtherargs]})\index{CallMethods@\texttt{CallMethods}}
\label{CallMethods}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a record \texttt{ms} describing this method selection procedure. 



 The argument \mbox{\texttt{\slshape db}} must be a method database in the sense of Section \ref{whataremethods}. \mbox{\texttt{\slshape limit}} must be a non-negative integer. \mbox{\texttt{\slshape furtherargs}} stands for an arbitrary number of additional arguments, which are handed down
to the called methods. Of course they must fulfill the conventions defined for
the methods in the database \mbox{\texttt{\slshape db}}.

 The function first creates a ``method selection'' record keeping track of the things that happened during the method trying
procedure, which is also used during this procedure. Then it calls methods
with the algorithm described below and in the end returns the method selection
record in its final state. }

 The method selection record has the following components: 
\begin{description}
\item[{\texttt{falsemethods}}] a record, in which for every method that returned \texttt{false} the value 1 is bound to the component with name the stamp of the method.
\item[{\texttt{failedmethods}}] a record, in which for every time a method returned \texttt{fail} the value bound to the component with name the stamp of the method is
increased by 1 (not being bound means zero).
\item[{\texttt{successmethod}}] the stamp of the method that succeeded, if one did. This component is only
bound after successful completion.
\item[{\texttt{result}}] a boolean value which is either \texttt{true} or \texttt{fail} depending on whether a successful method was found or the procedure gave up
respectively. This component is only bound after completion of the method
selection procedure.
\item[{\texttt{tolerance}}] the number of times all methods failed until one succeeded. See below.
\end{description}
 The algorithm used by \texttt{CallMethods} (\ref{CallMethods}) is extremely simple: It sets a counter \texttt{tolerance} to zero. The main loop starts at the beginning of the method database and runs
through the methods in turn. Provided a method did not yet return \texttt{false} and did not yet return \texttt{fail} more than \texttt{tolerance} times before, it is tried. According to the value returned by the method, the
following happens: 
\begin{description}
\item[{\texttt{false}}] this is marked in the method selection record and the main loop starts again
at the beginning of the method database.
\item[{\texttt{fail}}] this is counted in the method selection record and the main loop starts again
at the beginning of the method database.
\item[{\texttt{NotApplicable}}] the main loop goes to the next method in the method database.
\item[{\texttt{true}}] this is marked in the method selection record and the procedure returns
successfully.
\end{description}
 If the main loop reaches the end of the method database without calling a
method (because all methods have already failed or are not applicable), then
the counter \texttt{tolerance} is increased by one and everything starts all over again. This is repeated
until \texttt{tolerance} is greater than the \texttt{limit} which is the second argument of \texttt{CallMethods} (\ref{CallMethods}). The last value of the \texttt{tolerance} counter is returned in the component \texttt{tolerance} of the method selection record.

 Note that the main loop starts again at the beginning of the method database
after each failed method call! However, this does not lead to an infinite
loop, because the failure is recorded in the method selection record such that
the method is skipped until the \texttt{tolerance} increases. Once the \texttt{tolerance} has been increased methods having returned \texttt{fail} will be called again. The idea behind this approach is that even failed
methods can collect additional information about the arguments changing them
accordingly. This might give methods that come earlier and were not applicable
up to now the opportunity to begin working. Therefore one can install very
good methods that depend on some already known knowledge which will only be
acquired during the method selection procedure by other methods, with a high
rank.

 }

 

  }

  
\chapter{\textcolor{Chapter }{Group Recognition}}\label{recognition}
\logpage{[ 4, 0, 0 ]}
\hyperdef{L}{X7F73983582251807}{}
{
  This chapter describes a generic framework for group recognition. The basic
problem is, we want to solve the constructive membership problem: given any $g \in G$, $G = \langle X \rangle$, write a straight line program (SLP) from $X$ to $g$, for $g \notin G$ (in the situation that $G$ is naturally embedded into some bigger group), the algorithm should fail. This
is usually done by constructing some nice generators (and then writing an SLP
from the nice generators to $g$ and concatenating with an SLP from $X$ to the nice generators). Often, for efficiency reasons, we will just store the
nice generators and then only be interested in the SLP from those to $g$. The framework presented here deals with exactly this process.

 The generic framework was designed having four situations in mind: permutation
groups, matrix groups, projective groups and black box groups. Although the
methods used are quite different for those four cases, there is a common
pattern in the procedure of recognition. Namely, first we have to find a
homomorphism, solve the constructive membership problem recursively in image
and kernel, then put it together. The recursion ends in groups where we can
solve the constructive membership problem directly. The general framework
reflects this idea and separates it from the rest of the recognition methods.

 Solution of the constructive membership problem comes in two stages: first a ``recognition phase'' and then a ``verification phase''. The recognition phase usually consists of randomised algorithms with certain
error or failure probabilities. The result is some kind of ``recognition information'' that will describe the group already very well, but which is not yet proven to
be correct. However, one can already write arbitrary elements in the group as
product of the given generators. In the verification phase a presentation of
the group is calculated, thereby proving that the group generated by the given
generators is in fact isomorphic to the group described by the recognition
information. In many cases the verification phase will be much more expensive
than the recognition phase. 

 In the following sections, we describe the generic framework. We begin with a
technical description of the recursive procedure and describe then the way
methods to find homomorphism have to be implemented. Finally, we have four
sections in which we collect conventions for the recognition of different
types of groups.

 No actual recognition methods are implemented in this package. See the \textsf{recog} package for an implementation and description of them. 
\section{\textcolor{Chapter }{The recursive procedure}}\label{techrecog}
\logpage{[ 4, 1, 0 ]}
\hyperdef{L}{X81E31E377B16CF39}{}
{
  As explained at the beginning of this section, the heart of the recognition
procedure is a function called \texttt{RecogniseGeneric} (\ref{RecogniseGeneric}) which gets a \textsf{GAP} group object and returns a so-called ``recognition info record'' (see Subsection \ref{rirecord} for details). Success or failure will be indicated by this record being in the
filter \texttt{IsReady} (\ref{IsReady}) or not.

 To know how to find homomorphisms the function gets as another argument a
database of methods (see Section \ref{findhomo} for a description of the setup for methods for finding homomorphisms and
Section \ref{whataremethods} in Chapter \ref{methsel} for details about method databases). This database will be different according
to the type of group in question.

 To describe the algorithm executed by \texttt{RecogniseGeneric} (\ref{RecogniseGeneric}) we first summarise it in steps: 
\begin{enumerate}
\item Create a new, empty recognition info record.
\item Use the database of \texttt{FindHomomorphism} methods and the method selection procedure described in Chapter \ref{methsel} to try to find a homomorphism onto a smaller group or an isomorphism onto
another known group. Terminate with failure if this does not work.
\item If an isomorphism is found or a method somehow else recognises the group in
question, such that we can write elements as straight line programs in the
generators from now on, then make the recognition info record a leaf of the
recognition tree and return success.
\item Otherwise the function sets up all the data for the homomorphism and calls
itself with the image of the homomorphism. Note that this might use another
database of recognition methods because the homomorphism might change the
representation of the group.
\item After successful recognition of the factor group the procedure has to
recognise the kernel of the homomorphism. The first step for this is to find
generators. If they are not already known from the \texttt{FindHomomorphism} method, they are created by producing random elements in the group, mapping
them through the homomorphism, writing them as a straight line program in the
images of the generators and applying this straight line program to the
original generators. The quotient of the random element and the result of the
straight line program lies in the kernel of the homomorphism. After creating
20 random generators of the kernel we assume for the moment that they generate
the kernel. 
\item The function \texttt{RecogniseGeneric} (\ref{RecogniseGeneric}) can now call itself for the kernel. After successful recognition of the kernel
all the data for the node is completed and success is returned.
\item The function \texttt{RecogniseGeneric} (\ref{RecogniseGeneric}) now acquires preimages of the nice generators behind the homomorphism and
appends the nice generators of the kernel. This list of generators is now the
list of nice generators for the current node.
\end{enumerate}
 Note that with the collected data one can write arbitrary elements of the
group as a straight line program in the generators as follows: 
\begin{enumerate}
\item Map the element through the homomorphism.
\item Write the element in the factor group as a product of the nice generators in
the factor group.
\item Apply the resulting straight line program to the preimages of those nice
generators and calculate the quotient, which will now lie in the kernel.
\item Write the kernel element as a straight line program in the kernel generators.
\item Assemble both straight line programs to one bigger straight line program
(which is now in terms of our own nice generators) and return it.
\end{enumerate}
 If this procedure fails in the fourth step, this indicates that our random
generators for the kernel did not yet generate the full kernel and makes
further recognition steps necessary. This will not happen after a successful
verification phase.

 The latter procedure to write elements as straight line programs in the
generators is implemented in the function \texttt{SLPforElementGeneric} (\ref{SLPforElementGeneric}) which will be called automatically if one calls the \texttt{SLPforElement} (\ref{SLPforElement}) function of the resulting recognition info record (see \texttt{slpforelement} (\ref{slpforelement})).

 It is now high time to give you the calling details of the main recursive
recognition function: 

\subsection{\textcolor{Chapter }{RecogniseGeneric}}
\logpage{[ 4, 1, 1 ]}\nobreak
\hyperdef{L}{X7BFEB34483548A89}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RecogniseGeneric({\slshape H, methoddb, depth[, knowledge]})\index{RecogniseGeneric@\texttt{RecogniseGeneric}}
\label{RecogniseGeneric}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RecognizeGeneric({\slshape H, methoddb, depth[, knowledge]})\index{RecognizeGeneric@\texttt{RecognizeGeneric}}
\label{RecognizeGeneric}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
\texttt{fail} for failure or a recognition info record.



 \mbox{\texttt{\slshape H}} must be a \textsf{GAP} group object, \mbox{\texttt{\slshape methoddb}} must be a method database in the sense of Section \ref{whataremethods} containing \texttt{FindHomomorphism} methods in the sense of Section \ref{findhomo}. \mbox{\texttt{\slshape depth}} is an integer which measures the depth in the recognition tree. It will be
increased by one for each step we go into the tree. The top level has depth 0. \mbox{\texttt{\slshape knowledge}} is an optional record the components of which are copied into the new
recognition info record which is created for the group \mbox{\texttt{\slshape H}}. Especially the component \texttt{hints} can contain a list of additional find homomorphism methods (described by
records as in Section \ref{whataremethods}) which is prepended to the method database in \mbox{\texttt{\slshape methoddb}} before the recognition starts. This feature is intended to give hints about
prior knowledge about which find homomorphism method might succeed. 

 The function performs the algorithm described above and returns either \texttt{fail} in case of failure or a recognition info record in case of success. For the
content and definition of recognition info records see Section \ref{rirecord}. }

 The user will usually not call this function directly, but will use the
following convenience functions: 

\subsection{\textcolor{Chapter }{RecognisePermGroup}}
\logpage{[ 4, 1, 2 ]}\nobreak
\hyperdef{L}{X84338F037B91CDD0}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RecognisePermGroup({\slshape H})\index{RecognisePermGroup@\texttt{RecognisePermGroup}}
\label{RecognisePermGroup}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RecognizePermGroup({\slshape H})\index{RecognizePermGroup@\texttt{RecognizePermGroup}}
\label{RecognizePermGroup}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
\texttt{fail} for failure or a recognition info record.



 \mbox{\texttt{\slshape H}} must be a \textsf{GAP} permutation group object. This function calls \texttt{RecogniseGeneric} (\ref{RecogniseGeneric}) with the method database used for permutation groups, which is stored in the
global variable \texttt{FindHomDbPerm} (\ref{FindHomDbPerm}), and no prior knowledge. }

 

\subsection{\textcolor{Chapter }{RecogniseMatrixGroup}}
\logpage{[ 4, 1, 3 ]}\nobreak
\hyperdef{L}{X788DCF6A7D9E80BD}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RecogniseMatrixGroup({\slshape H})\index{RecogniseMatrixGroup@\texttt{RecogniseMatrixGroup}}
\label{RecogniseMatrixGroup}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RecognizeMatrixGroup({\slshape H})\index{RecognizeMatrixGroup@\texttt{RecognizeMatrixGroup}}
\label{RecognizeMatrixGroup}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
\texttt{fail} for failure or a recognition info record.



 \mbox{\texttt{\slshape H}} must be a \textsf{GAP} matrix group object. This function calls \texttt{RecogniseGeneric} (\ref{RecogniseGeneric}) with the method database used for matrix groups, which is stored in the global
variable \texttt{FindHomDbMatrix} (\ref{FindHomDbMatrix}), and no prior knowledge. }

 

\subsection{\textcolor{Chapter }{RecogniseProjectiveGroup}}
\logpage{[ 4, 1, 4 ]}\nobreak
\hyperdef{L}{X841176DD7BA1CAA0}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RecogniseProjectiveGroup({\slshape H})\index{RecogniseProjectiveGroup@\texttt{RecogniseProjectiveGroup}}
\label{RecogniseProjectiveGroup}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RecognizeProjectiveGroup({\slshape H})\index{RecognizeProjectiveGroup@\texttt{RecognizeProjectiveGroup}}
\label{RecognizeProjectiveGroup}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
\texttt{fail} for failure or a recognition info record.



 \mbox{\texttt{\slshape H}} must be a \textsf{GAP} matrix group object. Since as of now no actual projective groups are
implemented in the \textsf{GAP} library we use matrix groups instead. The recognition will however view the
group as the projective group, i.e. the matrix group modulo its scalar
matrices. This function calls \texttt{RecogniseGeneric} (\ref{RecogniseGeneric}) with the method database used for projective groups, which is stored in the
global variable \texttt{FindHomDbProjective} (\ref{FindHomDbProjective}), and no prior knowledge. }

 

\subsection{\textcolor{Chapter }{RecogniseBBGroup}}
\logpage{[ 4, 1, 5 ]}\nobreak
\hyperdef{L}{X8463F0AA7B1B71CB}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RecogniseBBGroup({\slshape H})\index{RecogniseBBGroup@\texttt{RecogniseBBGroup}}
\label{RecogniseBBGroup}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RecognizeBBGroup({\slshape H})\index{RecognizeBBGroup@\texttt{RecognizeBBGroup}}
\label{RecognizeBBGroup}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
\texttt{fail} for failure or a recognition info record.



 \mbox{\texttt{\slshape H}} must be a \textsf{GAP} black box group object. This function calls \texttt{RecogniseGeneric} (\ref{RecogniseGeneric}) with the method database used for black box groups, which is stored in the
global variable \texttt{FindHomDbBB} (\ref{FindHomDbBB}), and no prior knowledge. }

 

\subsection{\textcolor{Chapter }{RecogniseGroup}}
\logpage{[ 4, 1, 6 ]}\nobreak
\hyperdef{L}{X853B4EE27AF57CD3}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RecogniseGroup({\slshape H})\index{RecogniseGroup@\texttt{RecogniseGroup}}
\label{RecogniseGroup}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RecognizeGroup({\slshape H})\index{RecognizeGroup@\texttt{RecognizeGroup}}
\label{RecognizeGroup}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
\texttt{fail} for failure or a recognition info record.



 \mbox{\texttt{\slshape H}} must be a \textsf{GAP} group object. This function automatically dispatches to one of the three
previous functions \texttt{RecognisePermGroup} (\ref{RecognisePermGroup}), \texttt{RecogniseMatrixGroup} (\ref{RecogniseMatrixGroup}), or \texttt{RecogniseBBGroup} (\ref{RecogniseBBGroup}), according to the type of the group \mbox{\texttt{\slshape H}}. Note that since currently there is no implementation of projective groups in
the \textsf{GAP} library, one cannot recognise a matrix group \mbox{\texttt{\slshape H}} as a projective group using this function. }

 

\subsection{\textcolor{Chapter }{FindHomDbPerm}}
\logpage{[ 4, 1, 7 ]}\nobreak
\hyperdef{L}{X836B50947A46B1A5}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FindHomDbPerm\index{FindHomDbPerm@\texttt{FindHomDbPerm}}
\label{FindHomDbPerm}
}\hfill{\scriptsize (global variable)}}\\


 This list contains the methods for finding homomorphisms for permutation group
recognition that are stored in the record \texttt{FindHomMethodsPerm} (\ref{FindHomMethodsPerm}). As described in Section \ref{whataremethods} each method is described by a record. The list is always sorted with respect
to decreasing ranks. The order in this list tells in which order the methods
should be applied. Use \texttt{AddMethod} (\ref{AddMethod}) to add methods to this database. }

 

\subsection{\textcolor{Chapter }{FindHomMethodsPerm}}
\logpage{[ 4, 1, 8 ]}\nobreak
\hyperdef{L}{X7A94720080D344DA}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FindHomMethodsPerm\index{FindHomMethodsPerm@\texttt{FindHomMethodsPerm}}
\label{FindHomMethodsPerm}
}\hfill{\scriptsize (global variable)}}\\


 In this global record the functions that are methods for finding homomorphisms
for permutation group recognition are stored. We collect them all in this
record such that we do not use up too many global variable names. }

 

\subsection{\textcolor{Chapter }{SLPforElementFuncsPerm}}
\logpage{[ 4, 1, 9 ]}\nobreak
\hyperdef{L}{X7B5561D187242287}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SLPforElementFuncsPerm\index{SLPforElementFuncsPerm@\texttt{SLPforElementFuncsPerm}}
\label{SLPforElementFuncsPerm}
}\hfill{\scriptsize (global variable)}}\\


 This global record holds the functions that are methods for writing group
elements as straight line programs (SLPs) in terms of the generators after
successful permutation group recognition. We collect them all in this record
such that we do not use up too many global variable names. }

 

\subsection{\textcolor{Chapter }{FindHomDbMatrix}}
\logpage{[ 4, 1, 10 ]}\nobreak
\hyperdef{L}{X7CA5F5FA7E850885}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FindHomDbMatrix\index{FindHomDbMatrix@\texttt{FindHomDbMatrix}}
\label{FindHomDbMatrix}
}\hfill{\scriptsize (global variable)}}\\


 This list contains the methods for finding homomorphisms for matrix group
recognition that are stored in the record \texttt{FindHomMethodsMatrix} (\ref{FindHomMethodsMatrix}). As described in Section \ref{whataremethods} each method is described by a record. The list is always sorted with respect
to decreasing ranks. The order in this list tells in which order the methods
should be applied. Use \texttt{AddMethod} (\ref{AddMethod}) to add methods to this database. }

 

\subsection{\textcolor{Chapter }{FindHomMethodsMatrix}}
\logpage{[ 4, 1, 11 ]}\nobreak
\hyperdef{L}{X79B60CEF8292F142}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FindHomMethodsMatrix\index{FindHomMethodsMatrix@\texttt{FindHomMethodsMatrix}}
\label{FindHomMethodsMatrix}
}\hfill{\scriptsize (global variable)}}\\


 In this global record the functions that are methods for finding homomorphisms
for matrix group recognition are stored. We collect them all in this record
such that we do not use up too many global variable names. }

 

\subsection{\textcolor{Chapter }{SLPforElementFuncsMatrix}}
\logpage{[ 4, 1, 12 ]}\nobreak
\hyperdef{L}{X7A2E7DF67F4949C8}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SLPforElementFuncsMatrix\index{SLPforElementFuncsMatrix@\texttt{SLPforElementFuncsMatrix}}
\label{SLPforElementFuncsMatrix}
}\hfill{\scriptsize (global variable)}}\\


 This global record holds the functions that are methods for writing group
elements as straight line programs (SLPs) in terms of the generators after
successful matrix group recognition. We collect them all in this record such
that we do not use up too many global variable names. }

 

\subsection{\textcolor{Chapter }{FindHomDbProjective}}
\logpage{[ 4, 1, 13 ]}\nobreak
\hyperdef{L}{X7A4F8342854507E3}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FindHomDbProjective\index{FindHomDbProjective@\texttt{FindHomDbProjective}}
\label{FindHomDbProjective}
}\hfill{\scriptsize (global variable)}}\\


 This list contains the methods for finding homomorphisms for projective group
recognition that are stored in the record \texttt{FindHomMethodsProjective} (\ref{FindHomMethodsProjective}). As described in Section \ref{whataremethods} each method is described by a record. The list is always sorted with respect
to decreasing ranks. The order in this list tells in which order the methods
should be applied. Use \texttt{AddMethod} (\ref{AddMethod}) to add methods to this database. }

 

\subsection{\textcolor{Chapter }{FindHomMethodsProjective}}
\logpage{[ 4, 1, 14 ]}\nobreak
\hyperdef{L}{X7D796A2179E9026A}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FindHomMethodsProjective\index{FindHomMethodsProjective@\texttt{FindHomMethodsProjective}}
\label{FindHomMethodsProjective}
}\hfill{\scriptsize (global variable)}}\\


 In this global record the functions that are methods for finding homomorphisms
for projective group recognition are stored. We collect them all in this
record such that we do not use up too many global variable names. }

 

\subsection{\textcolor{Chapter }{SLPforElementFuncsProjective}}
\logpage{[ 4, 1, 15 ]}\nobreak
\hyperdef{L}{X7F6FCC4F81ACF20F}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SLPforElementFuncsProjective\index{SLPforElementFuncsProjective@\texttt{SLPforElementFuncsProjective}}
\label{SLPforElementFuncsProjective}
}\hfill{\scriptsize (global variable)}}\\


 This global record holds the functions that are methods for writing group
elements as straight line programs (SLPs) in terms of the generators after
successful projective group recognition. We collect them all in this record
such that we do not use up too many global variable names. }

 

\subsection{\textcolor{Chapter }{FindHomDbBB}}
\logpage{[ 4, 1, 16 ]}\nobreak
\hyperdef{L}{X7C3021F381A54203}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FindHomDbBB\index{FindHomDbBB@\texttt{FindHomDbBB}}
\label{FindHomDbBB}
}\hfill{\scriptsize (global variable)}}\\


 This list contains the methods for finding homomorphisms for black box group
recognition that are stored in the record \texttt{FindHomMethodsBB} (\ref{FindHomMethodsBB}). As described in Section \ref{whataremethods} each method is described by a record. The list is always sorted with respect
to decreasing ranks. The order in this list tells in which order the methods
should be applied. Use \texttt{AddMethod} (\ref{AddMethod}) to add methods to this database. }

 

\subsection{\textcolor{Chapter }{FindHomMethodsBB}}
\logpage{[ 4, 1, 17 ]}\nobreak
\hyperdef{L}{X7BC8D0158242150D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FindHomMethodsBB\index{FindHomMethodsBB@\texttt{FindHomMethodsBB}}
\label{FindHomMethodsBB}
}\hfill{\scriptsize (global variable)}}\\


 In this global record the functions that are methods for finding homomorphisms
for black box group recognition are stored. We collect them all in this record
such that we do not use up too many global variable names. }

 

\subsection{\textcolor{Chapter }{SLPforElementFuncsBB}}
\logpage{[ 4, 1, 18 ]}\nobreak
\hyperdef{L}{X7E762E1D86A31695}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SLPforElementFuncsBB\index{SLPforElementFuncsBB@\texttt{SLPforElementFuncsBB}}
\label{SLPforElementFuncsBB}
}\hfill{\scriptsize (global variable)}}\\


 This global record holds the functions that are methods for writing group
elements as straight line programs (SLPs) in terms of the generators after
successful black box group recognition. We collect them all in this record
such that we do not use up too many global variable names. }

 }

 
\section{\textcolor{Chapter }{Recognition info records}}\label{rirecord}
\logpage{[ 4, 2, 0 ]}
\hyperdef{L}{X7D7B4A3D81878179}{}
{
  A recognition info record is a \textsf{GAP} positional object. It is a member of the family 

\subsection{\textcolor{Chapter }{RecognitionInfoFamily}}
\logpage{[ 4, 2, 1 ]}\nobreak
\hyperdef{L}{X820267927AB548EC}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RecognitionInfoFamily\index{RecognitionInfoFamily@\texttt{RecognitionInfoFamily}}
\label{RecognitionInfoFamily}
}\hfill{\scriptsize (family)}}\\
}

 and is in the category 

\subsection{\textcolor{Chapter }{IsRecognitionInfo}}
\logpage{[ 4, 2, 2 ]}\nobreak
\hyperdef{L}{X836958B87C783165}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsRecognitionInfo\index{IsRecognitionInfo@\texttt{IsRecognitionInfo}}
\label{IsRecognitionInfo}
}\hfill{\scriptsize (Category)}}\\
}

 and is \texttt{IsAttributeStoringRep} (\textbf{Prg Tutorial: IsAttributeStoringRep}), such that we can define attributes for it, the values of which are stored
once they are known. A recognition info record always represents a whole
binary tree of such records, see the attributes \texttt{RIFac} (\ref{RIFac}) and \texttt{RIKer} (\ref{RIKer}) below. 

 The following filters are defined for recognition info records: 

\subsection{\textcolor{Chapter }{IsLeaf}}
\logpage{[ 4, 2, 3 ]}\nobreak
\hyperdef{L}{X8469BB658377FD92}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsLeaf\index{IsLeaf@\texttt{IsLeaf}}
\label{IsLeaf}
}\hfill{\scriptsize (Flag)}}\\


 This flag indicates, whether or not a recognition info record represents a
leaf in the recognition tree. If it is not set, one finds at least one of the
attributes \texttt{RIFac} (\ref{RIFac}) and \texttt{RIKer} (\ref{RIKer}) set for the corresponding node. This flag is normally reset and has to be set
by a find homomorphism method to indicate a leaf. }

 

\subsection{\textcolor{Chapter }{IsReady}}
\logpage{[ 4, 2, 4 ]}\nobreak
\hyperdef{L}{X7D6CEF0178ED73A7}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsReady\index{IsReady@\texttt{IsReady}}
\label{IsReady}
}\hfill{\scriptsize (Flag)}}\\


 This flag indicates during the recognition procedure, whether a node in the
recognition tree is already completed or not. It is mainly set for debugging
purposes during the recognition. However, if the recognition fails somewhere
in a leaf, this flag is not set and all nodes above will also not have this
flag set. In this way one can see whether the recognition failed and where the
problem was. If a find homomorphism method uses \texttt{donotrecurse} (see \ref{componentsri}) to avoid further recursion it acquires thereby responsibility to set the \texttt{IsReady} flag in the corresponding subtree upon completion. }

 The following attributes are defined for recognition info records: 

\subsection{\textcolor{Chapter }{Grp}}
\logpage{[ 4, 2, 5 ]}\nobreak
\hyperdef{L}{X7972380780D99B04}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Grp({\slshape ri})\index{Grp@\texttt{Grp}}
\label{Grp}
}\hfill{\scriptsize (attribute)}}\\


 The value of this attribute is the group that is to be recognised by this
recognition info record \mbox{\texttt{\slshape ri}}. This attribute is always present during recognition and after completion.
Note that the generators of the group object stored here always have a memory
attached to them, such that elements that are generated from them remember,
how they were acquired. }

 

\subsection{\textcolor{Chapter }{Homom}}
\logpage{[ 4, 2, 6 ]}\nobreak
\hyperdef{L}{X8273C2FC79FB6543}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Homom({\slshape ri})\index{Homom@\texttt{Homom}}
\label{Homom}
}\hfill{\scriptsize (attribute)}}\\


 The value of this attribute is the homomorphism that was found from the group
described by the recognition info record \mbox{\texttt{\slshape ri}} as a \textsf{GAP} object. It is set by a find homomorphism method that succeeded to find a
homomorphism (or isomorphism). It does not have to be set in leaf nodes of the
recognition tree. }

 

\subsection{\textcolor{Chapter }{NiceGens}}
\logpage{[ 4, 2, 7 ]}\nobreak
\hyperdef{L}{X864194958685AAD7}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{NiceGens({\slshape ri})\index{NiceGens@\texttt{NiceGens}}
\label{NiceGens}
}\hfill{\scriptsize (attribute)}}\\


 The value of this attribute must be set for all nodes and contains the nice
generators. The \texttt{SLPforElement} (\ref{SLPforElement}) function of the node will write its straight line program in terms of these
nice generators. For leaf nodes, the find homomorphism method is responsible
to set the value of \texttt{NiceGens}. By default, the original generators of the group at this node are taken. For
a homomorphism (or isomorphism), the \texttt{NiceGens} will be the concatenation of preimages of the \texttt{NiceGens} of the factor group (see \texttt{pregensfac} (\ref{pregensfac})) and the \texttt{NiceGens} of the kernel. A find homomorphism method does not have to set \texttt{NiceGens} if it finds a homomorphism. Note however, that such a find homomorphism method
has to ensure somehow, that preimages of the \texttt{NiceGens} of the factor group can be acquired. See \texttt{calcnicegens} (\ref{calcnicegens}), \texttt{CalcNiceGens} (\ref{CalcNiceGens}) and \texttt{slptonice} (\ref{slptonice}) for instructions. }

 

\subsection{\textcolor{Chapter }{pregensfac}}
\logpage{[ 4, 2, 8 ]}\nobreak
\hyperdef{L}{X808A01AA869115EC}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{pregensfac({\slshape ri})\index{pregensfac@\texttt{pregensfac}}
\label{pregensfac}
}\hfill{\scriptsize (attribute)}}\\


 The value of this attribute is only set for homomorphism nodes. In that case
it contains preimages of the nice generators in the factor group. This
attribute is set automatically by the generic recursive recognition function
using the mechanism described with the attribute \texttt{calcnicegens} (\ref{calcnicegens}) below. A find homomorphism does not have to touch this attribute. }

 

\subsection{\textcolor{Chapter }{RIFac}}
\logpage{[ 4, 2, 9 ]}\nobreak
\hyperdef{L}{X85D69105867342C7}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RIFac({\slshape ri})\index{RIFac@\texttt{RIFac}}
\label{RIFac}
}\hfill{\scriptsize (attribute)}}\\


 The value of this attribute is the recognition info record of the image of the
homomorphism that was found from the group described by the recognition info
record \mbox{\texttt{\slshape ri}}. It is set by the generic recursive procedure after a find homomorphism
method has succeeded to find a homomorphism (or isomorphism). It does not have
to be set in leaf nodes of the recognition tree. This attribute value provides
the link to the ``factor'' subtree of the recognition tree. }

 

\subsection{\textcolor{Chapter }{RIKer}}
\logpage{[ 4, 2, 10 ]}\nobreak
\hyperdef{L}{X85B6D66F7BD0E964}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RIKer({\slshape ri})\index{RIKer@\texttt{RIKer}}
\label{RIKer}
}\hfill{\scriptsize (attribute)}}\\


 The value of this attribute is the recognition info record of the kernel of
the homomorphism that was found from the group described by the recognition
info record \mbox{\texttt{\slshape ri}}. It is set by the generic recursive procedure after a find homomorphism
method has succeeded to find a homomorphism (or isomorphism). It does not have
to be set in leaf nodes of the recognition tree or if the homomorphism is
known to be an isomorphism. In the latter case the value of the attribute is
set to \texttt{fail}. This attribute value provides the link to the ``kernel'' subtree of the recognition tree. }

 

\subsection{\textcolor{Chapter }{RIParent}}
\logpage{[ 4, 2, 11 ]}\nobreak
\hyperdef{L}{X7C66C89C84F9C6AA}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RIParent({\slshape ri})\index{RIParent@\texttt{RIParent}}
\label{RIParent}
}\hfill{\scriptsize (attribute)}}\\


 The value of this attribute is the recognition info record of the parent of
this node in the recognition tree. The top node does not have this attribute
set. }

 

\subsection{\textcolor{Chapter }{fhmethsel}}
\logpage{[ 4, 2, 12 ]}\nobreak
\hyperdef{L}{X7ACD6B4C7982B1E3}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{fhmethsel({\slshape ri})\index{fhmethsel@\texttt{fhmethsel}}
\label{fhmethsel}
}\hfill{\scriptsize (attribute)}}\\


 The value of this attribute is the record returned by the method selection
(see Section \ref{howcalled}) after it ran to find a homomorphism (or isomorphism). It is there to be able
to see which methods were tried until the recognition of the node was
completed. }

 

\subsection{\textcolor{Chapter }{slpforelement}}
\logpage{[ 4, 2, 13 ]}\nobreak
\hyperdef{L}{X83167779869A3BF5}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{slpforelement({\slshape ri})\index{slpforelement@\texttt{slpforelement}}
\label{slpforelement}
}\hfill{\scriptsize (attribute)}}\\


 After the recognition phase is completed for the node \mbox{\texttt{\slshape ri}}, we are by definition able to write arbitrary elements in the group described
by this node as a straight line program (SLP) in terms of the nice generators
stored in \texttt{NiceGens} (\ref{NiceGens}). This attribute value is a function taking the node \mbox{\texttt{\slshape ri}} and a group element as its arguments and returning the above mentioned
straight line program. For the case that a find homomorphism method succeeds
in finding a homomorphism, the generic recursive function sets this attribute
to the function \texttt{SLPforElementGeneric} (\ref{SLPforElementGeneric}) which does the job for the generic homomorphism situation. In all other cases
the successful find homomorphism method has to set this attribute to a
function doing the job. The find homomorphism method is free to store
additional data in the recognition info record or the group object such that
the \texttt{SLPforElement} (\ref{SLPforElement}) function can work. }

 

\subsection{\textcolor{Chapter }{SLPforElement}}
\logpage{[ 4, 2, 14 ]}\nobreak
\hyperdef{L}{X83167779869A3BF5}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SLPforElement({\slshape ri, x})\index{SLPforElement@\texttt{SLPforElement}}
\label{SLPforElement}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a straight line program expressing \mbox{\texttt{\slshape x}} in the nice generators. 



 This is a wrapper function which extracts the value of the attribute \texttt{slpforelement} (\ref{slpforelement}) and calls that function with the arguments \mbox{\texttt{\slshape ri}} and \mbox{\texttt{\slshape x}}. }

 

\subsection{\textcolor{Chapter }{StdPresentation}}
\logpage{[ 4, 2, 15 ]}\nobreak
\hyperdef{L}{X7FBE4706828964EB}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StdPresentation({\slshape ri})\index{StdPresentation@\texttt{StdPresentation}}
\label{StdPresentation}
}\hfill{\scriptsize (attribute)}}\\


 After the verification phase, the presentation is stored here. Details have
still to be decided upon. }

 

\subsection{\textcolor{Chapter }{methodsforfactor}}
\logpage{[ 4, 2, 16 ]}\nobreak
\hyperdef{L}{X826BC2BB7D7AD6A9}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{methodsforfactor({\slshape ri})\index{methodsforfactor@\texttt{methodsforfactor}}
\label{methodsforfactor}
}\hfill{\scriptsize (attribute)}}\\


 This attribute is initialised at the beginning of the recursive recognition
function with the database of find homomorphism methods that was used to
recognise the group corresponding to the recognition info record \mbox{\texttt{\slshape ri}}. If the found homomorphism changes the representation of the group (going for
example from a matrix group to a permutation group), the find homomorphism
method can report this by exchanging the database of find homomorphism methods
to be used in the recognition of the image of the homomorphism by setting the
value of this attribute to something different. It lies in the responsibility
of the find homomorphism method to do so, if the representation changes
through the homomorphism. }

 The following two attributes are concerned with the relation between the
original generators and the nice generators for a node. They are used to
transport this information from a successful find homomorphism method up to
the recursive recognition function: 

\subsection{\textcolor{Chapter }{calcnicegens}}
\logpage{[ 4, 2, 17 ]}\nobreak
\hyperdef{L}{X7EFA298E7E4760A0}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{calcnicegens({\slshape ri})\index{calcnicegens@\texttt{calcnicegens}}
\label{calcnicegens}
}\hfill{\scriptsize (attribute)}}\\


 To make the recursion work, we have to acquire preimages of the nice
generators in factor groups under the homomorphism found. But we want to keep
the information, how the nice generators were found, locally at the node where
they were found. This attribute solves this problem of acquiring preimages in
the following way: Its value must be a function, taking the recognition info
record \mbox{\texttt{\slshape ri}} as first argument, and a list \mbox{\texttt{\slshape origgens}} of preimages of the original generators of the current node, and has to return
corresponding preimages of the nice generators. Usually this task can be done
by storing a straight line program writing the nice generators in terms of the
original generators and executing this with inputs \mbox{\texttt{\slshape origgens}}. Therefore the default value of this attribute is the function \texttt{CalcNiceGensGeneric} (\ref{CalcNiceGensGeneric}) described below. }

 

\subsection{\textcolor{Chapter }{CalcNiceGensGeneric}}
\logpage{[ 4, 2, 18 ]}\nobreak
\hyperdef{L}{X78B05A1E78564BBF}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CalcNiceGensGeneric({\slshape ri, origgens})\index{CalcNiceGensGeneric@\texttt{CalcNiceGensGeneric}}
\label{CalcNiceGensGeneric}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a list of preimages of the nice generators



 This is the default function for leaf nodes for the attribute \texttt{calcnicegens} (\ref{calcnicegens}) described above. It does the following: If the value of the attribute \texttt{slptonice} (\ref{slptonice}) is set, then it must be a straight line program expressing the nice generators
in terms of the original generators of this node. In that case, this straight
line program is executed with \mbox{\texttt{\slshape origgens}} as inputs and the result is returned. Otherwise, \mbox{\texttt{\slshape origgens}} is returned as is. Therefore a leaf node just has to do nothing if the nice
generators are equal to the original generators, or can simply store the right
straight line program into the attribute \texttt{slptonice} (\ref{slptonice}) to fulfill its duties. }

 

\subsection{\textcolor{Chapter }{CalcNiceGensHomNode}}
\logpage{[ 4, 2, 19 ]}\nobreak
\hyperdef{L}{X80444E4E8501D0B0}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CalcNiceGensHomNode({\slshape ri, origgens})\index{CalcNiceGensHomNode@\texttt{CalcNiceGensHomNode}}
\label{CalcNiceGensHomNode}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a list of preimages of the nice generators



 This is the default function for homomorphism node for the attribute \texttt{calcnicegens} (\ref{calcnicegens}). It just delegates to factor and kernel of the homomorphism, as the nice
generators of a homomorphism (or isomorphism) node are just the concatenation
of the nice generators of the factor and the kernel. A find homomorphism
method finding a homomorphism or isomorphism does not have to do anything with
respect to nice generators. }

 

\subsection{\textcolor{Chapter }{CalcNiceGens}}
\logpage{[ 4, 2, 20 ]}\nobreak
\hyperdef{L}{X7EFA298E7E4760A0}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CalcNiceGens({\slshape ri, origgens})\index{CalcNiceGens@\texttt{CalcNiceGens}}
\label{CalcNiceGens}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a list of preimages of the nice generators



 This is a wrapper function which extracts the value of the attribute \texttt{calcnicegens} (\ref{calcnicegens}) and calls that function with the arguments \mbox{\texttt{\slshape ri}} and \mbox{\texttt{\slshape origgens}}. }

 

\subsection{\textcolor{Chapter }{slptonice}}
\logpage{[ 4, 2, 21 ]}\nobreak
\hyperdef{L}{X80C2451F805CA06D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{slptonice({\slshape ri})\index{slptonice@\texttt{slptonice}}
\label{slptonice}
}\hfill{\scriptsize (attribute)}}\\


 As described above, the value, if set, must be a straight line program
expressing the nice generators at this node in terms of the original
generators. This is for leaf nodes, that choose to use the default function \texttt{CalcNiceGensGeneric} (\ref{CalcNiceGensGeneric}) installed in the \texttt{calcnicegens} (\ref{calcnicegens}) attribute. }

 The following three attributes are concerned with the administration of the
kernel of a found homomorphism. Find homomorphism methods use them to report
to the main recursive recognition function their knowledge about the kernel: 

\subsection{\textcolor{Chapter }{gensN}}
\logpage{[ 4, 2, 22 ]}\nobreak
\hyperdef{L}{X7B7E9EAC7AACF8D8}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{gensN({\slshape ri})\index{gensN@\texttt{gensN}}
\label{gensN}
}\hfill{\scriptsize (attribute)}}\\


 The value of this mutable attribute is a list of generators of the kernel of
the homomorphism found at the node \mbox{\texttt{\slshape ri}}. It is initialised as an empty list when the recursive recognition function
starts. Successful find homomorphism methods may append generators of the
kernel to this list if they happen to stumble on them. After successful
recognition of the image of the homomorphism the main recursive recognition
function will try to create a few more generators of the kernel and append
them to the list which is the value of the attribute \texttt{gensN}. The exact behaviour depends on the value of the attribute \texttt{findgensNmeth} (\ref{findgensNmeth}) below. The list of generators after that step is used to recognise the kernel.
Note that the generators in \texttt{gensN} have a memory attached to them, how they were obtained in terms of the
original generators of the current node. }

 

\subsection{\textcolor{Chapter }{findgensNmeth}}
\logpage{[ 4, 2, 23 ]}\nobreak
\hyperdef{L}{X81644C3A8064063F}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{findgensNmeth({\slshape ri})\index{findgensNmeth@\texttt{findgensNmeth}}
\label{findgensNmeth}
}\hfill{\scriptsize (attribute)}}\\


 This attribute decides about how generators of the kernel of a found
homomorphism are produced. Its value has to be a record with at least two
components bound. The first is \texttt{method} which holds a function taking at least one argument \mbox{\texttt{\slshape ri}} and possibly more, and does not return anything. The second is \texttt{args} which holds a list of arguments for the above mentioned function. The real
list of arguments is derived by prepending the recognition info record to the
list of arguments in \texttt{args}. That is, the following code is used to call the method: 
\begin{Verbatim}[fontsize=\small,frame=single,label=]
      methgensN := findmethgensN(ri);
      CallFuncList(methgensN(ri).method,Concatenation([ri],methgensN.args));
\end{Verbatim}
 The record is initialised upon creation of the recognition info record to
calling \texttt{FindKernelRandom} (\ref{FindKernelRandom}) with one argument of 20 (in addition to the first argument \mbox{\texttt{\slshape ri}}). See below for a choice of possible find kernel methods. }

 

\subsection{\textcolor{Chapter }{FindKernelRandom}}
\logpage{[ 4, 2, 24 ]}\nobreak
\hyperdef{L}{X7DC1D16F807D6895}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FindKernelRandom({\slshape ri, n})\index{FindKernelRandom@\texttt{FindKernelRandom}}
\label{FindKernelRandom}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 \mbox{\texttt{\slshape n}} random elements are generated, mapped through the homomorphism, written as a
straight line program in the generators. Then the straight line program is
executed with the original generators thereby producing elements in the same
coset. The quotients are then elements of the kernel. The kernel elements
created are stored in the attribute \texttt{gensN} (\ref{gensN}). }

 

\subsection{\textcolor{Chapter }{FindKernelDoNothing}}
\logpage{[ 4, 2, 25 ]}\nobreak
\hyperdef{L}{X8244F0DE86C23ECA}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FindKernelDoNothing({\slshape ri, n})\index{FindKernelDoNothing@\texttt{FindKernelDoNothing}}
\label{FindKernelDoNothing}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 Does nothing. This function is intended to be set as method for producing
kernel elements if the kernel is known to be trivial or if one knows, that the
attribute \texttt{gensN} (\ref{gensN}) already contains a complete set of generators for the kernel. }

 

\subsection{\textcolor{Chapter }{FindKernelFastNormalClosure}}
\logpage{[ 4, 2, 26 ]}\nobreak
\hyperdef{L}{X87E8AB1B78F60112}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FindKernelFastNormalClosure({\slshape ri, nr})\index{FindKernelFastNormalClosure@\texttt{FindKernelFastNormalClosure}}
\label{FindKernelFastNormalClosure}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a probable generating set for the normal closure



 This function takes the group $G$ in the \texttt{Grp} (\ref{Grp}) attribute in \mbox{\texttt{\slshape ri}} and the list of generators $gens$ of the kernel in \texttt{gensN} (\ref{gensN}) and the positive integer \mbox{\texttt{\slshape nr}}. This function computes a probable generating set of the normal closure in \mbox{\texttt{\slshape G}} of the group generated by the generators in \mbox{\texttt{\slshape gens}}. The integer \mbox{\texttt{\slshape nr}} indicates how hard it should try. }

 

\subsection{\textcolor{Chapter }{gensNslp}}
\logpage{[ 4, 2, 27 ]}\nobreak
\hyperdef{L}{X82154EA88011654F}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{gensNslp({\slshape ri})\index{gensNslp@\texttt{gensNslp}}
\label{gensNslp}
}\hfill{\scriptsize (attribute)}}\\


 The recursive recognition function calculates a straight line program that
computes the generators of the kernel stored in \texttt{gensN} (\ref{gensN}) in terms of the generators of the group recognised by \mbox{\texttt{\slshape ri}}. This straight line program is stored in the value of this mutable attribute.
It is used by the generic function \texttt{SLPforElementGeneric} (\ref{SLPforElementGeneric}). }

 

\subsection{\textcolor{Chapter }{immediateverification}}
\logpage{[ 4, 2, 28 ]}\nobreak
\hyperdef{L}{X86A101E17F87F01F}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{immediateverification({\slshape ri})\index{immediateverification@\texttt{immediateverification}}
\label{immediateverification}
}\hfill{\scriptsize (attribute)}}\\


 Sometimes a find homomorphism has information that it will be difficult to
create generators for the kernel, for example if it is known that the kernel
will need lots of generators. In that case this attribute with the default
boolean value \texttt{false} can be set to \texttt{true}. In that case, the generic recursive recognition function will perform an
immediate verification phase after the kernel has been recognised. This is
done as follows: A few random elements are created, mapped through the
homomorphism and written as an SLP in the nice generators there. Then this SLP
is executed with preimages of those nice generators. The quotient lies then in
the kernel and is written as an SLP in terms of the nice generators of the
would be kernel. If this is not possible, then probably the creation of kernel
generators was not complete and a few more kernel elements are produced and
recognition in the kernel starts all over again. This is for example done in
case of the ``Imprimitive'' method which maps onto the action on a block system. In that case, the kernel
often needs lots of generators. }

 The following attributes are used to give a successful find homomorphism
method further possibilities to transport knowledge about the group recognised
by the current recognition info record to the factor or kernel of the found
homomorphism: 

\subsection{\textcolor{Chapter }{forkernel}}
\logpage{[ 4, 2, 29 ]}\nobreak
\hyperdef{L}{X87B550967D90B794}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{forkernel({\slshape ri})\index{forkernel@\texttt{forkernel}}
\label{forkernel}
}\hfill{\scriptsize (attribute)}}\\


 This attribute is initialised to a record with only the component \texttt{hints} bound to an empty list at the beginning of the recursive recognition function.
Find homomorphism methods can put acquired knowledge about the group to be
recognised (like for example an invariant subspace of a matrix group) into
this record. When a homomorphism is found and recognition goes on in its
kernel, the value of this attribute is taken as initialisation data for the
newly created recognition info record for the kernel. Thus, information is
transported down to the recognition process for the kernel. The component \texttt{hints} is special insofar as it has to contain records describing find homomorphism
methods which might be particularly successful. They are prepended to the find
homomorphism method database such that they are called before any other
methods. This is a means to give hints to the recognition procedure in the
kernel, because often during the finding of a homomorphism knowledge is
acquired which might help the recognition of the kernel. }

 

\subsection{\textcolor{Chapter }{forfactor}}
\logpage{[ 4, 2, 30 ]}\nobreak
\hyperdef{L}{X7CBBF7FC8200790C}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{forfactor({\slshape ri})\index{forfactor@\texttt{forfactor}}
\label{forfactor}
}\hfill{\scriptsize (attribute)}}\\


 This attribute is initialised to a record with only the component \texttt{hints} bound to an empty list at the beginning of the recursive recognition function.
Find homomorphism methods can put acquired knowledge about the group to be
recognised (like for example an invariant subspace of a matrix group) into
this record. When a homomorphism is found and recognition goes on in its
image, the value of this attribute is taken as initialisation data for the
newly created recognition info record for the factor. Thus, information is
transported down to the recognition process for the factor. The component \texttt{hints} is special insofar as it has to contain records describing find homomorphism
methods which might be particularly successful. They are prepended to the find
homomorphism method database such that they are called before any other
methods. This is a means to give hints to the recognition procedure in the
factor, because often during the finding of a homomorphism knowledge is
acquired which might help the recognition of the factor. }

 

\subsection{\textcolor{Chapter }{isone}}
\logpage{[ 4, 2, 31 ]}\nobreak
\hyperdef{L}{X814D78347858EC13}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{isone({\slshape ri})\index{isone@\texttt{isone}}
\label{isone}
}\hfill{\scriptsize (attribute)}}\\


 This attribute returns a function that tests, whether or not an element of the
group is equal to the identity or not. Usually this is just the operation \texttt{IsOne} (\textbf{Reference: IsOne}) but for projective groups it is a special function returning \texttt{true} for scalar matrices. In generic code, one should always use the result of this
attribute to compare an element to the identity such that the code works also
for projective groups. Find homomorphism methods usually do not have to set
this attribute. }

 

\subsection{\textcolor{Chapter }{isequal}}
\logpage{[ 4, 2, 32 ]}\nobreak
\hyperdef{L}{X7D0F06047B88E5CD}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{isequal({\slshape ri})\index{isequal@\texttt{isequal}}
\label{isequal}
}\hfill{\scriptsize (attribute)}}\\


 This attribute returns a function that compares two elements of the group
being recognised. Usually this is just the operation \texttt{EQ} (\textbf{Reference: Equality and Comparison of Domains}) but for projective groups it is a special function checking for equality up to
a scalar factor. In generic code, one should always use the result of this
attribute to compare two elements such that the code works also for projective
groups. Find homomorphism methods usually do not have to set this attribute. }

 
\subsection{\textcolor{Chapter }{Other components of recognition info records}}\label{componentsri}
\logpage{[ 4, 2, 33 ]}
\hyperdef{L}{X800B9BBE82F24C49}{}
{
  In this subsection we describe a few more components of recognition info
records that can be queried or set by find homomorphism methods. Not all of
these components are bound in all cases. See the individual descriptions about
the conventions. Remember to use the \texttt{!.} notation to access these components of a recognition info record. 
\begin{description}
\item[{\texttt{donotrecurse}}]  This component can be set to \texttt{true} by a find homomorphism method to indicate that the generic recursive procedure
should not recurse further down, even if the corresponding node is not a leaf.
It is then the responsibility of the find homomorphism method to complete the
tree below. 
\item[{\texttt{leavegensNuntouched}}] If this component is bound to \texttt{true} by a find homomorphism method or a find kernel generators method, the generic
mechanism to remove duplicates and identities in the generator for the kernel
is not used. This is important if your methods rely on the generating set of
the kernel being exactly as it was when found. 
\end{description}
 }

 }

 
\section{\textcolor{Chapter }{Methods to find homomorphisms}}\label{findhomo}
\logpage{[ 4, 3, 0 ]}
\hyperdef{L}{X8577717D85D631C2}{}
{
  A ``find homomorphism method'' has the objective to, given a group $G$, either find a homomorphism from $G$ onto a group, or to find an isomorphism, or to solve the constructive
membership problem directly for $G$, or to fail. 

 In case a homomorphism is found, it has to report that homomorphism back to
the calling recursive recognition function together with as much information
about the kernel as possible.

 If a find homomorphism method determines that the node is a leaf in the
recognition tree (by solving the constructive membership problem directly),
then it has to ensure, that arbitrary elements can be written in terms of the
nice generators of $G$. It does so by returning a function together with possible extra data, that
can perform this job.

 Of course, the find homomorphism method also has to report, how the nice
generators were acquired in terms of the original generators.

 If the find homomorphism method fails, it has to report, whether it has failed
forever or if it possibly makes sense to try to call this method again later. 

 Find homomorphism methods have to fit into the framework for method selection
described in Chapter \ref{methsel}. We now begin to describe the technical details of how a find homomorphism
method has to look like and what it has to do and what it is not allowed to
do. We first explain the calling convention by means of a hypothetical
function: 

\subsection{\textcolor{Chapter }{FindHomomorphism}}
\logpage{[ 4, 3, 1 ]}\nobreak
\hyperdef{L}{X7FCBB7C686D0B1DF}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FindHomomorphism({\slshape ri, G})\index{FindHomomorphism@\texttt{FindHomomorphism}}
\label{FindHomomorphism}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
One of the values \texttt{true}, \texttt{false}, \texttt{fail}, or \texttt{NotApplicable}.



 Find homomorphism methods take two arguments \mbox{\texttt{\slshape ri}} and \mbox{\texttt{\slshape G}}, of which \mbox{\texttt{\slshape ri}} is a recognition info record and \mbox{\texttt{\slshape G}} is a \textsf{GAP} group object. The return value is one of the four possible values in the
framework for method selection described in Chapter \ref{methsel} indicating success, failure, or (temporary) non-applicability. The above
mentioned additional information in case of success are all returned by
changing the recognition info record \mbox{\texttt{\slshape ri}}. For the conventions about what a find homomorphism method has to do and
return see below. }

 A failed or not applicable find homomorphism method does not have to report or
do anything in the recognition info record \mbox{\texttt{\slshape ri}}. However, it can collect information and store it either in the group object
or in the recognition info record. Note that for example it might be that a
failed find homomorphism method acquires additional information that allows
another find homomorphism method to become applicable. 

 A not applicable find homomorphism method should find out so relatively
quickly, because otherwise the whole process might be slowed down, because a
find homomorphism method repeatedly ponders about its applicability. Usually
no big calculations should be triggered just to decide applicability.

 A successful find homomorphism method has the following duties: 
\begin{description}
\item[{for leaves:}] First it has to report whether the current node is a leaf or not in the
recognition tree. That is, in case a leaf was found the method has to do \texttt{SetFilterObj(ri,IsLeaf);} thereby setting the \texttt{IsLeaf} (\ref{IsLeaf}) flag. 

 If the method for some reason chooses to finish the tree below the current
node on its own, it can set the component \texttt{donotrecurse} to \texttt{true} (see \ref{componentsri}) to indicate that no further action is required by the generic recognition
function. The method is then responsible for correctly setting the \texttt{IsLeaf} (\ref{IsLeaf}) and \texttt{IsReady} (\ref{IsReady}) flags in the whole subtree. 

 A method finding a homomorphism which is not an isomorphism indicates so by
not touching the flags. 
\item[{for leaves: \texttt{SLPforElement} (\ref{SLPforElement}) function}]  If a find homomorphism method has produced a leaf in the recognition tree or
has set the \texttt{donotrecurse} component to \texttt{true} (see \ref{componentsri}), then it has to set the attribute \texttt{slpforelement} (\ref{slpforelement}) to a function like \texttt{SLPforElementGeneric} (\ref{SLPforElementGeneric}) that can write an arbitrary element in \mbox{\texttt{\slshape G}} as a straight line program in the nice generators of \mbox{\texttt{\slshape G}}. The method may store additional data into the recognition info record for
this to work. It does not have to set any other value in \mbox{\texttt{\slshape ri}}. 
\item[{for leaves: information about nice generators}]  If a find homomorphism method has produced a leaf in the recognition tree,
then it has to report what are the nice generators of the group described by
the leaf. To this end, it has three possibilities: Firstly to do nothing,
which means, that the original generators are the nice generators. Secondly to
store a straight line program expressing the nice generators in terms of the
original generators into the attribute \texttt{slptonice} (\ref{slptonice}). In that case, the generic frame work takes care of the rest. The third
possibility is to store a function into the value of the attribute \texttt{calcnicegens} (\ref{calcnicegens}) which can calculate preimages of the nice generators in terms of preimages of
the original generators. See the function \texttt{CalcNiceGensGeneric} (\ref{CalcNiceGensGeneric}) for an example of such a function. 
\item[{for non-leaves: the homomorphism itself}]  If a find homomorphism method has found a homomorphism, it has to store it as
a \textsf{GAP} homomorphism object from \mbox{\texttt{\slshape G}} to the image group in the attribute \texttt{Homom} (\ref{Homom}). Note that if your homomorphism changes the representation (for example going
from matrix groups to permutation groups), you will have to set the attribute \texttt{methodsforfactor} (\ref{methodsforfactor}) accordingly. 
\item[{for non-leaves: kernel generators}]  If a find homomorphism method has found a homomorphism, it has to provide
information about already known generators of the kernel. This is done firstly
by appending known generators of the kernel to the attribute value of \texttt{gensN} (\ref{gensN}) and secondly by leaving or changing the attribute \texttt{findgensNmeth} (\ref{findgensNmeth}) to a record describing the method that should be used (for details see \texttt{findgensNmeth} (\ref{findgensNmeth})). If one does not change the default value, the recursive recognition
function will generate 20 random elements in \mbox{\texttt{\slshape G}} and produce random generators of the kernel by dividing by a preimage of an
image under the homomorphism. Note that generators in \texttt{gensN} (\ref{gensN}) have to have a memory attached to them that stores, how they were acquired
from the generators of \mbox{\texttt{\slshape G}}. 
\item[{additional information}]  A find homomorphism method may store any data into the attributes \texttt{forkernel} (\ref{forkernel}) and \texttt{forfactor} (\ref{forfactor}), which both are records. Components in these record that are bound during the
recognition will be copied into the recognition info record of the kernel and
factor respectively of a found homomorphism upon creation and thus are
available to all find homomorphism methods called for the kernel and factor.
This feature might be interesting to transport information that is relevant
for the recognition of the kernel or factor and was acquired during the
recognition of \mbox{\texttt{\slshape G}} itself.

 A special role is played by the component \texttt{hints} in both of the above records, which can hold a list of records describing find
homomorphism methods that shall be tried first when recognising the kernel or
factor. 

 In addition, a find homomorphism method might set the attribute \texttt{immediateverification} (\ref{immediateverification}) to true, if it considers the problem of finding kernel generators particularly
difficult. 
\end{description}
 To explain the calling conventions for \texttt{SLPforElement} (\ref{SLPforElement}) functions and for the sake of completeness we present now the function \texttt{SLPforElementGeneric} (\ref{SLPforElementGeneric}) which is used for the case of a ``homomorphism node'': 

\subsection{\textcolor{Chapter }{SLPforElementGeneric}}
\logpage{[ 4, 3, 2 ]}\nobreak
\hyperdef{L}{X7F299344834AAB6E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SLPforElementGeneric({\slshape ri, x})\index{SLPforElementGeneric@\texttt{SLPforElementGeneric}}
\label{SLPforElementGeneric}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a \textsf{GAP} straight line program



 This function takes as arguments a recognition info record \mbox{\texttt{\slshape ri}} and a group element \mbox{\texttt{\slshape x}}. It returns a \textsf{GAP} straight line program that expresses the element \mbox{\texttt{\slshape x}} in terms of the nice generators of the group $G$ recognised by \mbox{\texttt{\slshape ri}}.

 This generic function here does exactly this job for the generic situation
that we found a homomorphism from $G$ to some other group say $H$ with kernel $N$. It first maps \mbox{\texttt{\slshape x}} via the homomorphism to $H$ and uses the recognition information there to write it as a straight line
program in terms of the nice generators of $H$. Then it applies this straight line program to the preimages of those nice
generators (see \texttt{pregensfac} (\ref{pregensfac})) thereby finding an element $y$ of $G$ with $x \cdot y^{-1}$ lying in the kernel $N$. 

 Then the function writes this element as a straight line program in the nice
generators of $N$ again using the recursively acquired recognition info about $N$. In the end a concatenated straight line program for $x$ is built, which is in terms of the nice generators of the current node. }

 }

 
\section{\textcolor{Chapter }{Conventions for the recognition of permutation groups}}\label{convperm}
\logpage{[ 4, 4, 0 ]}
\hyperdef{L}{X7B2941D57B361990}{}
{
  No conventions so far. }

 
\section{\textcolor{Chapter }{Conventions for the recognition of matrix groups}}\label{convmat}
\logpage{[ 4, 5, 0 ]}
\hyperdef{L}{X8676A21280D842DB}{}
{
  We are considering only the case of matrix groups over finite fields.

 No conventions so far. }

 
\section{\textcolor{Chapter }{Conventions for the recognition of projective groups}}\label{convproj}
\logpage{[ 4, 6, 0 ]}
\hyperdef{L}{X835738DA86087BB3}{}
{
  We are considering only the case of projective groups over finite fields.

 No conventions so far. }

 
\section{\textcolor{Chapter }{Conventions for the recognition of black box groups}}\label{convbb}
\logpage{[ 4, 7, 0 ]}
\hyperdef{L}{X853D4D0F82D40D6A}{}
{
  No conventions so far. }

  }

  
\chapter{\textcolor{Chapter }{After successful recognition}}\label{afterrecog}
\logpage{[ 5, 0, 0 ]}
\hyperdef{L}{X851A3F04786123D5}{}
{
  This chapter explains, what one can do with recognition info records after a
successful recognition (and possibly verification).

 Of course, one can inspect the whole tree of recognition info records just by
looking at the stored attribute values. Moreover, constructive membership
tests can be performed using the function \texttt{SLPforElement} (\ref{SLPforElement}), thereby writing an arbitrary element in terms of the nice generators, which
are stored in the attribute \texttt{NiceGens} (\ref{NiceGens}). If \texttt{fail} is returned, then the element in question does not lie in the recognised group
or the recognition made an error.

 Here is an example of a successful recognition tree: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> g := DirectProduct(SymmetricGroup(12),SymmetricGroup(5));
  Group([ (1,2,3,4,5,6,7,8,9,10,11,12), (1,2), (13,14,15,16,17), (13,14) ])
  gap> ri := RecogniseGroup(g);
  #I  Finished rank 90 method "NonTransitive": success.
  #I  Going to the factor (depth=0, try=1).
  #I  Finished rank 95 method "VeryFewPoints": success.
  #I  Back from factor (depth=0).
  #I  Calculating preimages of nice generators.
  #I  Creating 20 random generators for kernel.
  ....................
  #I  Going to the kernel (depth=0).
  #I  Finished rank 80 method "Giant": success.
  #I  Back from kernel (depth=0).
  <recoginfo NonTransitive
   F:<recoginfo VeryFewPoints Size=120>
   K:<recoginfo Giant Size=479001600>>
\end{Verbatim}
 One sees that the recursive process runs, first it finds that the permutation
action is not transitive, a homomorphism is found by mapping onto the action
on one of the orbits. The image is recognised to permute only a few points.
The kernel is recognised to be a full symmetric group in its natural action on
at least 10 points (recognised as ``Giant''). 

 After this, we can write arbitrary group elements in the group \texttt{g} in terms of the nice generators: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> x := PseudoRandom(g);
  (1,12)(2,5,9,11,10,3,4)(7,8)(13,14,16,15,17)
  gap> slp := SLPforElement(ri,x);
  <straight line program>
  gap> ResultOfStraightLineProgram(slp,NiceGens(ri));
  (1,12)(2,5,9,11,10,3,4)(7,8)(13,14,16,15,17)
\end{Verbatim}
 Note that this example only works by using also the \textsf{recog} package which contains the necessary recognition methods. 
\section{\textcolor{Chapter }{Functions and methods for recognition info records}}\logpage{[ 5, 1, 0 ]}
\hyperdef{L}{X803CC158789AADDA}{}
{
  If you need an element explicitly written in terms of the original generators,
you can use the following function: 

\subsection{\textcolor{Chapter }{SLPforNiceGens}}
\logpage{[ 5, 1, 1 ]}\nobreak
\hyperdef{L}{X82F5B37186B949BF}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SLPforNiceGens({\slshape ri})\index{SLPforNiceGens@\texttt{SLPforNiceGens}}
\label{SLPforNiceGens}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
an SLP expressing the nice generators in the original ones



 This function assembles a possibly quite large straight line program
expressing the nice generators in terms of the original ones by using the
locally stored information in the recognition tree recursively.

 You can concatenate straight line programs in the nice generators with the
result of this function to explicitly write an element in terms of the
original generators. }

 

\subsection{\textcolor{Chapter }{\texttt{\symbol{92}}in}}
\logpage{[ 5, 1, 2 ]}\nobreak
\hyperdef{L}{X87BDB89B7AAFE8AD}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{\texttt{\symbol{92}}in({\slshape x, ri})\index{in@\texttt{\texttt{\symbol{92}}in}}
\label{in}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
\texttt{true} or \texttt{false}



 This method tests, whether the element \mbox{\texttt{\slshape x}} lies in the group recognised by the recognition info record \mbox{\texttt{\slshape ri}}. Note that this is only a convenience method, in fact \texttt{SLPforElement} (\ref{SLPforElement}) is used and the resulting straight line program is thrown away. }

 

\subsection{\textcolor{Chapter }{Size}}
\logpage{[ 5, 1, 3 ]}\nobreak
\hyperdef{L}{X858ADA3B7A684421}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Size({\slshape ri})\index{Size@\texttt{Size}}
\label{Size}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
the size of the recognised group



 This method calculates the size of the recognised group by multiplying the
size of the factor and the kernel recursively. It is assumed that leaf nodes
know already or can calculate the size of their group. }

 

\subsection{\textcolor{Chapter }{DisplayCompositionFactors}}
\logpage{[ 5, 1, 4 ]}\nobreak
\hyperdef{L}{X80FFBDCD816690E3}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DisplayCompositionFactors({\slshape ri})\index{DisplayCompositionFactors@\texttt{DisplayCompositionFactors}}
\label{DisplayCompositionFactors}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 This function displays a composition series by using the recursive recognition
tree. It only works, if the usual operation \texttt{CompositionSeries} (\textbf{Reference: CompositionSeries}) works for all leaves. THIS DOES CURRENTLY NOT WORK FOR PROJECTIVE GROUPS AND
THUS FOR MATRIX GROUPS! }

 }

  }

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

\bibliographystyle{alpha}
\bibliography{recogbase}

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


\printindex

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