%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  recognition.tex        IRREDSOL documentation          Burkhard Hoefling
%%
%%  @(#)$Id: recognition.tex,v 1.4 2005/07/06 10:08:23 gap Exp $
%%
%%  Copyright (C) 2003-2005 by Burkhard Hoefling, 
%%  Institut fuer Geometrie, Algebra und Diskrete Mathematik
%%  Technische Universitaet Braunschweig, Germany
%%


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Chapter{Recognition of matrix groups}

This chapter describes some functions which, given an irreducible matrix 
group, identify a group in the {\IRREDSOL} library which is conjugate
to that group, see Section~"Identification of irreducible groups".
Moreover,  Section "Compatibility with other data libraries" describes
how to  translate between groups in the {\IRREDSOL} library and the
{\GAP}  library of irreducible solvable groups. 
Section~"Loading and unloading recognition data manually" describes some 
functions which allow to load and unload the recognition data in the 
{\IRREDSOL} package manually.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Identification of irreducible groups}

\>`IsAvailableIdIrreducibleSolvableMatrixGroup(<G>)'%
{IsAvailableIdIrreducibleSolvableMatrixGroup}%
@{`IsAvailableIdIrreducible\\SolvableMatrixGroup'} F

This function returns `true' if `IdIrreducibleSolvableMatrixGroup' (see
"IdIrreducibleSolvableMatrixGroup") will work for the irreducible matrix group <G>, and `false' otherwise.

\>`IsAvailableIdAbsolutelyIrreducibleSolvableMatrixGroup(<G>)'%
{IsAvailableIdAbsolutelyIrreducibleSolvableMatrixGroup}%
@{`IsAvailableIdAbsolutelyIrreducible\\SolvableMatrixGroup'} F

This function returns `true' if `IdIrreducibleSolvableMatrixGroup' (see
"IdIrreducibleSolvableMatrixGroup") will work for the absolutely irreducible matrix group <G>, and `false' otherwise.


\>IdIrreducibleSolvableMatrixGroup(<G>) A

If the matrix group <G> is solvable and irreducible over $F
= `FieldOfMatrixGroup'(<G>)$, (see "ref:FieldOfMatrixGroup" in the {\GAP} reference manual), and a conjugate in
$GL(<n>, <F>)$ of $<G>$ belongs to the data base of  irreducible solvable groups in
{\IRREDSOL}, this function returns a list `[<n>, <q>, <d>, <k>]' such that <G> is
conjugate to  `IrreducibleSolvableMatrixGroup'(<n>, <q>, <d>, <k>) (see
"IrreducibleSolvableMatrixGroup").

\beginexample
gap> G := IrreducibleSolvableMatrixGroup (12, 2, 3, 52)^RandomInvertibleMat (12, GF(8));
<matrix group of size 2340 with 6 generators>
gap> IdIrreducibleSolvableMatrixGroup (G);
[ 12, 2, 3, 52 ]
\endexample


\>`RecognitionIrreducibleSolvableMatrixGroup(%
   <G>, <wantmat>, <wantgroup>)'%
{RecognitionIrreducibleSolvableMatrixGroup}%
@{`RecognitionIrreducibleSolvable\\MatrixGroup'} F
\>`RecognitionIrreducibleSolvableMatrixGroupNC(%
   <G>, <wantmat>,<wantgroup>)'%
{RecognitionIrreducibleSolvableMatrixGroupNC}%
@{`RecognitionIrreducibleSolvable\\MatrixGroupNC'} F

Let <G> be an irreducible solvable matrix group over a finite field, and let
<wantmat> and <wantmat> be `true' or `false'. 
These functions identify a conjugate <H> of <G> group in the library. 
They return a record which has the following entries:
\beginitems
`id' &  contains the id of <H> (and thus of
<G>); cf. `IdIrreducibleSolvableMatrixGroup'
("IdIrreducibleSolvableMatrixGroup")

`mat' (present if `wantmat' is `true') &
a
matrix <x> such that $G^x = H$

`group' (present if `wantmat' is `true') & the group <H> 

\enditems
Note that in most cases, `RecognitionIrreducibleSolvableMatrixGroup' and `RecognitionIrreducibleSolvableMatrixGroupNC' are 
much slower if <wantmat> is set to true.   

`RecognitionIrreducibleSolvableMatrixGroupNC' does not check its arguments. If
the group <G> is beyond the scope of the {\IRREDSOL} library (see "IsAvailableIdIrreducibleSolvableMatrixGroup"), `RecognitionIrreducibleSolvableMatrixGroupNC' returns `fail', while `RecognitionIrreducibleSolvableMatrixGroup' raises an error.

\beginexample
gap> G := IrreducibleSolvableMatrixGroup (6, 2, 3, 5) ^
>         RandomInvertibleMat (6, GF(4));
<matrix group of size 42 with 3 generators>
gap> r := RecognitionIrreducibleSolvableMatrixGroup (G, true, false);;
gap> r.id;
[ 6, 2, 3, 5 ]
gap> G^r.mat = CallFuncList (IrreducibleSolvableMatrixGroup, r.id);
true
\endexample


\>IdAbsolutelyIrreducibleSolvableMatrixGroup(<G>) A
\>`RecognitionAbsolutelyIrreducibleSolvableMatrixGroup(%
   <G>, <wantmat>, <wantgroup>)'%
{RecognitionAbsolutelyIrreducibleSolvableMatrixGroup}%
@{`RecognitionAbsolutelyIrreducibleSolvable\\MatrixGroup'} F
\>`RecognitionAbsolutelyIrreducibleSolvableMatrixGroupNC(%
   <G>, <wantmat>,<wantgroup>)'%
{RecognitionAbsolutelyIrreducibleSolvableMatrixGroupNC}%
@{`RecognitionAbsolutelyIrreducibleSolvable\\MatrixGroupNC'} F

These functions are no longer available. These functions have been replaced by the
functions 
`IdIrreducibleSolvableMatrixGroup' ("IdIrreducibleSolvableMatrixGroup"), 
`RecognitionIrreducibleSolvableMatrixGroup' ("RecognitionIrreducibleSolvableMatrixGroup"), or
`RecognitionIrreducibleSolvableMatrixGroupNC' ("RecognitionIrreducibleSolvableMatrixGroupNC").

Note that the ids returned by the functions for absolutely irreducible groups was a triple `[<n>, <d>, <k>]', while the replacement functions use ids of the form `[<n>, <d>, <d>, <k>]', where $<d> = 1$ in the absolutely irreducible case.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Compatibility with other data libraries}

A library of irreducible solvable subgroups of $GL(n, p)$, where $p$ is a 
prime and $p^n \leq 255$ already exists in {\GAP}, see Section "ref:Irreducible Solvable Matrix Groups" in the {\GAP} reference manual. The following functions
allow one to translate between between that library and the {\IRREDSOL} library. 


\>IdIrreducibleSolvableMatrixGroupIndexMS(<n>, <p>, <k>) F

This function returns the id (see "IdIrreducibleSolvableMatrixGroup") of <G>, 
where <G> is `IrreducibleSolvableGroupMS'(<n>, <p>, <k>) (see "ref:IrreducibleSolvableGroupMS" in the {\GAP} reference manual).

\beginexample
gap> IdIrreducibleSolvableMatrixGroupIndexMS (6, 2, 5);
[ 6, 2, 2, 4 ]
gap> G := IrreducibleSolvableGroupMS (6,2,5);
<matrix group of size 27 with 2 generators>
gap> H := IrreducibleSolvableMatrixGroup (6, 2, 2, 4);
<matrix group of size 27 with 3 generators>
gap> G = H;
false # groups in the libraries need not be the same
gap> r := RecognitionIrreducibleSolvableMatrixGroup (G, true, false);;
gap> G^r.mat = H;
true
\endexample

\>IndexMSIdIrreducibleSolvableMatrixGroup(<n>, <q>, <d>, <k>) F

This function returns a triple [<n>, <p>, <l>] such that
`IrreducibleSolvableGroupMS'(<n>, <p>, <l>) (see "ref:IrreducibleSolvableGroupMS" in the {\GAP} reference manual) is conjugate to
`IrreducibleSolvableMatrixGroup'(<n>, <q>, <d>, <k>) (see "IrreducibleSolvableMatrixGroup").

\beginexample
gap> IndexMSIdIrreducibleSolvableMatrixGroup (6, 2, 2, 7);
[ 6, 2, 13 ]
gap> G := IrreducibleSolvableGroupMS (6,2,13);
<matrix group of size 27 with 2 generators>
gap> H := IrreducibleSolvableMatrixGroup (6, 2, 2, 7);
<matrix group of size 27 with 3 generators>
gap> G = H;
false # groups in the libraries need not be the same
gap> r := RecognitionIrreducibleSolvableMatrixGroup (G, true, false);;
gap> G^r.mat = H;
true
\endexample


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Loading and unloading recognition data manually}

The data required by the {\IRREDSOL} library is loaded into {\GAP}'s workspace automatically whenever required, but is never unloaded automatically. The functions described in this
and the previous section describe how to load and unload this data manually. 
They are only relevant if timing or conservation of memory is an issue.
\index{workspace!running out of}
\>`LoadAbsolutelyIrreducibleSolvableGroupFingerprints(<n>, <q>)'%
{LoadAbsolutelyIrreducibleSolvableGroupFingerprints}%
@{`LoadAbsolutelyIrreducibleSolvableGroup\\Fingerprints'} F
This function loads the fingerprint data required for the recognition
of absolutely irreducible solvable subgroups of $GL(<n>, <q>)$.

\>`LoadedAbsolutelyIrreducibleSolvableGroupFingerprints()'%
{LoadedAbsolutelyIrreducibleSolvableGroupFingerprints}%
@{`LoadedAbsolutelyIrreducibleSolvableGroup\\Fingerprints'} F

This function returns a list. Each entry consists of an integer <n> and a set <l>. The set
<l> contains all prime powers <q> such that the recognition data for $GL(<n>, <q>)$ is currently in
memory.

\>`UnloadAbsolutelyIrreducibleSolvableGroupFingerprints([n [,q]])'%
{UnloadAbsolutelyIrreducibleSolvableGroupFingerprints}%
@{`UnloadAbsolutelyIrreducibleSolvableGroup\\Fingerprints'} F

This function can be used to delete recognition data for irreducible groups from the {\GAP} workspace. If no
argument is given, all data will be deleted. If only <n> is given, all data for degree <n> (and any
<q>) will be deleted. If <n> and <q> are given, only the data for $GL(n, q)$ will be deleted from the
{\GAP} workspace. Use this function if you run out of {\GAP} workspace. The
data is automatically re-loaded when required.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%E
%%