% This file was created automatically from grplib.msk.
% DO NOT EDIT!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%A  grplib.msk                  GAP documentation          Heiko Theissen
%A                                                         Volkmar Felsch
%A                                                         Bettina Eick
%A                                                         Alexander Hulpke
%A                                                         Hans Ulrich Besche
%%
%A  @(#)$Id: grplib.msk,v 1.78.2.4 2006/09/16 19:02:49 jjm Exp $
%%
%Y  (C) 1998 School Math and Comp. Sci., University of St.  Andrews, Scotland
%Y  Copyright (C) 2002 The GAP Group
%%
\Chapter{Group Libraries}

When you start {\GAP}, it  already knows several groups. Currently {\GAP}
initially knows the following groups:
\beginlist%unordered
  \item{$\bullet$} some basic groups, such  as cyclic groups or symmetric
    groups (see~"Basic Groups"),
  \item{$\bullet$} Classical matrix groups (see~"Classical Groups"),
  \item{$\bullet$} the transitive permutation groups of degree at most 30
    (see~"Transitive permutation groups"),
  \item{$\bullet$} a library of groups of small order (see~"Small Groups"),
  \item{$\bullet$}  the  finite perfect  groups of   size  at most $10^6$
    (excluding 11 sizes) (see~"Finite perfect groups").
  \item{$\bullet$}  the  primitive  permutation groups of degree
    $\<2499$ (see~"Primitive  permutation
    groups"),
  \item{$\bullet$}  the  irreducible solvable subgroups of  $GL(n,p)$ for
    $n>1$ and $p^n \< 256$ (see "Irreducible Solvable Matrix Groups"),
  \item{$\bullet$} the irreducible maximal finite integral matrix groups
    of dimension at most  31  (see~"Irreducible Maximal Finite Integral
    Matrix Groups"),
%\item{$\bullet$} the  crystallographic  groups  of  dimension  at most  4
%  (see~"The Crystallographic Groups Library").
\endlist

There   is usually no   relation  between the   groups  in the  different
libraries and a group may occur in different libraries in different
incarnations.

Note that a system administrator may choose to install all, or
only a  few,  or even  none of the  libraries.  So some  of the libraries
mentioned below may not be available on your installation.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Basic Groups}

There are several infinite families of groups which are parametrized by
numbers.
{\GAP} provides various functions to construct these groups.
The functions always permit (but do not require) one to indicate
a filter (see~"Filters"), for example `IsPermGroup', `IsMatrixGroup' or
`IsPcGroup', in which the group shall be constructed.
There always is a default filter corresponding to a ``natural'' way
to describe the group in question.
Note that not every group can be constructed in every filter,
there may be theoretical restrictions (`IsPcGroup' only works for
solvable groups) or methods may be available only for a few filters.

Certain filters may admit additional hints.
For example, groups constructed in `IsMatrixGroup' may be constructed
over a specified field, which can be given as second argument of the
function that constructs the group;
The default field is `Rationals'.


\>TrivialGroup( [<filter>] ) F

constructs a trivial group in the category given by the filter <filter>.
If <filter> is not given it defaults to `IsPcGroup'.


\beginexample
gap> TrivialGroup();
<pc group of size 1 with 0 generators>
gap> TrivialGroup( IsPermGroup );
Group(())
\endexample

\>CyclicGroup( [<filt>, ]<n> ) F

constructs the cyclic group of size <n> in the category given by the
filter <filt>.  If <filt> is not given it defaults to `IsPcGroup'.


\beginexample
gap> CyclicGroup(12);
<pc group of size 12 with 3 generators>
gap> CyclicGroup(IsPermGroup,12);
Group([ (1,2,3,4,5,6,7,8,9,10,11,12) ])
gap> matgrp1:= CyclicGroup( IsMatrixGroup, 12 );
<matrix group of size 12 with 1 generators>
gap> FieldOfMatrixGroup( matgrp1 );
Rationals
gap> matgrp2:= CyclicGroup( IsMatrixGroup, GF(2), 12 );
<matrix group of size 12 with 1 generators>
gap> FieldOfMatrixGroup( matgrp2 );
GF(2)
\endexample

\>AbelianGroup( [<filt>, ]<ints> ) F

constructs an abelian group in the category given by the filter <filt>
which is of isomorphism type $C_{ints[1]} \*  C_{ints[2]} \* \ldots \*
C_{ints[n]}$.  <ints> must be a list of positive integers.  If <filt> is
not given it defaults to `IsPcGroup'.  The generators of the group
returned are the elements corresponding to the integers in <ints>.


\beginexample
gap> AbelianGroup([1,2,3]);
<pc group of size 6 with 3 generators>
\endexample

\>ElementaryAbelianGroup( [<filt>, ]<n> ) F

constructs the elementary abelian group of size <n> in the category
given by the filter <filt>.
If <filt> is not given it defaults to `IsPcGroup'.


\beginexample
gap> ElementaryAbelianGroup(8192);
<pc group of size 8192 with 13 generators>
\endexample

\>DihedralGroup( [<filt>, ]<n> ) F

constructs the dihedral group of size <n> in the category given by the
filter <filt>.  If <filt> is not given it defaults to `IsPcGroup'.


\beginexample
gap> DihedralGroup(10);
<pc group of size 10 with 2 generators>
\endexample

\>ExtraspecialGroup( [<filt>, ]<order>, <exp> ) F

Let <order> be of the form $p^{2n+1}$, for a prime integer $p$ and a
positive integer $n$.
`ExtraspecialGroup' returns the extraspecial group of order <order>
that is determined by <exp>, in the category given by the filter <filt>.

If $p$ is odd then admissible values of <exp> are the exponent of the
group (either $p$ or $p^2$) or one of `{'}+{'}', `\"+\"', `{'}-{'}',
`\"-\"'.
For $p = 2$, only the above plus or minus signs are admissible.

If <filt> is not given it defaults to `IsPcGroup'.


\beginexample
gap> ExtraspecialGroup( 27, 3 );
<pc group of size 27 with 3 generators>
gap> ExtraspecialGroup( 27, '+' );
<pc group of size 27 with 3 generators>
gap> ExtraspecialGroup( 8, "-" );
<pc group of size 8 with 3 generators>
\endexample

\>AlternatingGroup( [<filt>, ]<deg> ) F
\>AlternatingGroup( [<filt>, ]<dom> ) F

constructs the alternating group of degree <deg> in the category given
by the filter <filt>.
If <filt> is not given it defaults to `IsPermGroup'.
In the second version, the function constructs the alternating group on
the points given in the set <dom> which must be a set of positive
integers.


\beginexample
gap> AlternatingGroup(5);
Alt( [ 1 .. 5 ] )
\endexample

\>SymmetricGroup( [<filt>, ]<deg> ) F
\>SymmetricGroup( [<filt>, ]<dom> ) F

constructs the symmetric group of degree <deg> in the category given by
the filter <filt>.
If <filt> is not given it defaults to `IsPermGroup'.
In the second version, the function constructs the symmetric group on
the points given in the set <dom> which must be a set of positive
integers.


\beginexample
gap> SymmetricGroup(10);
Sym( [ 1 .. 10 ] )
\endexample

Note that permutation groups provide special treatment of symmetric and
alternating groups, see~"Symmetric and Alternating Groups".

\>MathieuGroup( [<filt>, ]<degree> ) F

constructs the Mathieu group of degree <degree> in the category given by
the filter <filt>,
where <degree> must be in $\{ 9, 10, 11, 12, 21, 22, 23, 24 \}$.
If <filt> is not given it defaults to `IsPermGroup'.


\beginexample
gap> MathieuGroup( 11 );
Group([ (1,2,3,4,5,6,7,8,9,10,11), (3,7,11,8)(4,10,5,6) ])
\endexample

\>SuzukiGroup( [<filt>, ] <q> ) F
\>Sz( [<filt>, ] <q> ) F

Constructs a group isomorphic to the Suzuki group Sz( <q> )
over the field with <q> elements, where <q> is a non-square
power of 2.

If <filt> is not given it defaults to `IsMatrixGroup',
and the returned group is the Suzuki group itself.


\beginexample
gap> SuzukiGroup( 32 );
Sz(32)
\endexample

\>ReeGroup( [<filt>, ] <q> ) F
\>Ree( [<filt>, ] <q> ) F

Constructs a group isomorphic to the Ree group $2G2(q)$ where
$q=3^{1+2m}$ for $m$ a non-negative integer.

If <filt> is not given it defaults to `IsMatrixGroup' and
the generating matrices are based on~\cite{KLM01}.
(No particular choice of a generating set is guaranteed.)


\beginexample
gap> ReeGroup( 27 );
Ree(27)
\endexample


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Classical Groups}

The following functions return classical groups.
For the linear, symplectic, and unitary groups (the latter in dimension
at least $3$), the generators are taken from~\cite{Tay87};
for the unitary groups in dimension 2, the isomorphism of $SU(2,q)$ and
$SL(2,q)$ is used, see for example~\cite{Hup67}.
The generators of the orthogonal groups are taken
from~\cite{IshibashiEarnest94} and~\cite{KleidmanLiebeck90},
except that the generators of the orthogonal groups in odd dimension in
even characteristic are constructed via the isomorphism to a symplectic
group, see for example~\cite{Car72a}.

For symplectic and orthogonal matrix groups returned by the functions
described below, the invariant bilinear form is stored as the value of
the attribute `InvariantBilinearForm' (see~"InvariantBilinearForm").
Analogously, the invariant sesquilinear form defining the unitary groups
is stored as the value of the attribute `InvariantSesquilinearForm'
(see~"InvariantSesquilinearForm").
The defining quadratic form of orthogonal groups is stored as the value
of the attribute `InvariantQuadraticForm' (see~"InvariantQuadraticForm").



\>GeneralLinearGroup( [<filt>, ]<d>, <R> ) F
\>GL( [<filt>, ]<d>, <R> ) F
\>GeneralLinearGroup( [<filt>, ]<d>, <q> ) F
\>GL( [<filt>, ]<d>, <q> ) F

The first two forms construct a group isomorphic to the general linear
group GL( <d>, <R> ) of all $<d> \times <d>$ matrices that are invertible
over the ring <R>, in the category given by the filter <filt>.

The third and the fourth form construct the general linear group over the
finite field with <q> elements.

If <filt> is not given it defaults to `IsMatrixGroup',
and the returned group is the general linear group as a matrix group in
its natural action (see also~"IsNaturalGL", "IsNaturalGLnZ").

Currently supported rings <R> are finite fields, the ring `Integers',
and residue class rings `Integers mod <m>'.


\beginexample
gap> GL(4,3);
GL(4,3)
gap> GL(2,Integers);
GL(2,Integers)
gap> GL(3,Integers mod 12);
GL(3,Z/12Z)
\endexample

\>SpecialLinearGroup( [<filt>, ]<d>, <R> ) F
\>SL( [<filt>, ]<d>, <R> ) F
\>SpecialLinearGroup( [<filt>, ]<d>, <q> ) F
\>SL( [<filt>, ]<d>, <q> ) F

The first two forms construct a group isomorphic to the special linear
group SL( <d>, <R> ) of all those $<d> \times <d>$ matrices over the
ring <R> whose determinant is the identity of <R>,
in the category given by the filter <filt>.

The third and the fourth form construct the special linear group over the
finite field with <q> elements.

If <filt> is not given it defaults to `IsMatrixGroup',
and the returned group is the special linear group as a matrix group in
its natural action (see also~"IsNaturalSL", "IsNaturalSLnZ").

Currently supported rings <R> are finite fields, the ring `Integers',
and residue class rings `Integers mod <m>'.


\beginexample
gap> SpecialLinearGroup(2,2);
SL(2,2)
gap> SL(3,Integers);
SL(3,Integers)
gap> SL(4,Integers mod 4);
SL(4,Z/4Z)
\endexample

\indextt{OnLines!example}
Using the `OnLines' operation it is possible to obtain the corresponding
projective groups in a permutation action:

\beginexample
gap> g:=GL(4,3);;Size(g);
24261120
gap> pgl:=Action(g,Orbit(g,Z(3)^0*[1,0,0,0],OnLines),OnLines);;
gap> Size(pgl);
12130560
\endexample

\>GeneralUnitaryGroup( [<filt>, ]<d>, <q> ) F
\>GU( [<filt>, ]<d>, <q> ) F

constructs a group isomorphic to the general unitary group GU( <d>, <q> )
of those $<d> \times <d>$ matrices over the field with $<q>^2$ elements
that respect a fixed nondegenerate sesquilinear form,
in the category given by the filter <filt>.

If <filt> is not given it defaults to `IsMatrixGroup',
and the returned group is the general unitary group itself.


\beginexample
gap> GeneralUnitaryGroup( 3, 5 );
GU(3,5)
\endexample

\>SpecialUnitaryGroup( [<filt>, ]<d>, <q> ) F
\>SU( [<filt>, ]<d>, <q> ) F

constructs a group isomorphic to the special unitary group `GU(<d>, <q>)'
of those $<d> \times <d>$ matrices over the field with $<q>^2$ elements
whose determinant is the identity of the field and that respect a fixed
nondegenerate sesquilinear form,
in the category given by the filter <filt>.

If <filt> is not given it defaults to `IsMatrixGroup',
and the returned group is the special unitary group itself.


\beginexample
gap> SpecialUnitaryGroup( 3, 5 );
SU(3,5)
\endexample

\>SymplecticGroup( [<filt>, ]<d>, <q> ) F
\>Sp( [<filt>, ]<d>, <q> ) F
\>SP( [<filt>, ]<d>, <q> ) F

constructs a group isomorphic to the symplectic group Sp( <d>, <q> )
of those $<d> \times <d>$ matrices over the field with <q> elements
that respect a fixed nondegenerate symplectic form,
in the category given by the filter <filt>.

If <filt> is not given it defaults to `IsMatrixGroup',
and the returned group is the symplectic group itself.


\beginexample
gap> SymplecticGroup( 4, 2 );
Sp(4,2)
\endexample

\>GeneralOrthogonalGroup( [<filt>, ][<e>, ]<d>, <q> ) F
\>GO( [<filt>, ][<e>, ]<d>, <q> ) F

constructs a group isomorphic to the
general orthogonal group GO( <e>, <d>, <q> ) of those $<d> \times <d>$
matrices over the field with <q> elements that respect a non-singular
quadratic form (see~"InvariantQuadraticForm") specified by <e>,
in the category given by the filter <filt>.

The value of <e> must be $0$ for odd <d> (and can optionally be 
omitted in this case), respectively  one of  $1$ or $-1$ for even <d>.
If <filt> is not given it defaults to `IsMatrixGroup',
and the returned group is the general orthogonal group itself.

Note that in~\cite{KleidmanLiebeck90}, GO is defined as the stabilizer
$\Delta(V,F,\kappa)$ of the quadratic form, up to scalars,
whereas our GO is called $I(V,F,\kappa)$ there.


\>SpecialOrthogonalGroup( [<filt>, ][<e>, ]<d>, <q> ) F
\>SO( [<filt>, ][<e>, ]<d>, <q> ) F

`SpecialOrthogonalGroup' returns a group isomorphic to the 
special orthogonal group SO( <e>, <d>, <q> ), which is the subgroup of
all those matrices in the general orthogonal group
(see~"GeneralOrthogonalGroup") that have determinant one,
in the category given by the filter <filt>.
(The index of SO( <e>, <d>, <q> ) in GO( <e>, <d>, <q> ) is $2$ if <q> is
odd, and $1$ if <q> is even.)

If <filt> is not given it defaults to `IsMatrixGroup',
and the returned group is the special orthogonal group itself.


\beginexample
gap> GeneralOrthogonalGroup( 3, 7 );
GO(0,3,7)
gap> GeneralOrthogonalGroup( -1, 4, 3 );
GO(-1,4,3)
gap> SpecialOrthogonalGroup( 1, 4, 4 );
GO(+1,4,4)
\endexample

\>ProjectiveGeneralLinearGroup( [<filt>, ]<d>, <q> ) F
\>PGL( [<filt>, ]<d>, <q> ) F

constructs a group isomorphic to the projective general linear group
PGL( <d>, <q> ) of those $<d> \times <d>$ matrices over the field with
<q> elements, modulo the
centre, in the category given by the filter <filt>.

If <filt> is not given it defaults to `IsPermGroup',
and the returned group is the action on lines of the underlying vector
space.


\>ProjectiveSpecialLinearGroup( [<filt>, ]<d>, <q> ) F
\>PSL( [<filt>, ]<d>, <q> ) F

constructs a group isomorphic to the projective special linear group
PSL( <d>, <q> ) of those $<d> \times <d>$ matrices over the field with
<q> elements whose determinant is the identity of the field, modulo the
centre, in the category given by the filter <filt>.

If <filt> is not given it defaults to `IsPermGroup',
and the returned group is the action on lines of the underlying vector
space.


\>ProjectiveGeneralUnitaryGroup( [<filt>, ]<d>, <q> ) F
\>PGU( [<filt>, ]<d>, <q> ) F

constructs a group isomorphic to the projective general unitary group
PGU( <d>, <q> ) of those $<d> \times <d>$ matrices over the field with
$<q>^2$ elements that respect a fixed nondegenerate sesquilinear form,
modulo the centre, in the category given by the filter <filt>.

If <filt> is not given it defaults to `IsPermGroup',
and the returned group is the action on lines of the underlying vector
space.


\>ProjectiveSpecialUnitaryGroup( [<filt>, ]<d>, <q> ) F
\>PSU( [<filt>, ]<d>, <q> ) F

constructs a group isomorphic to the projective special unitary group
PSU( <d>, <q> ) of those $<d> \times <d>$ matrices over the field with
$<q>^2$ elements that respect a fixed nondegenerate sesquilinear form
and have determinant 1,
modulo the centre, in the category given by the filter <filt>.

If <filt> is not given it defaults to `IsPermGroup',
and the returned group is the action on lines of the underlying vector
space.


\>ProjectiveSymplecticGroup( [<filt>, ]<d>, <q> ) F
\>PSP( [<filt>, ]<d>, <q> ) F
\>PSp( [<filt>, ]<d>, <q> ) F

constructs a group isomorphic to the projective symplectic group
PSp(<d>,<q>) of those $<d> \times <d>$ matrices over the field with <q>
elements that respect a fixed nondegenerate symplectic form, modulo the
centre, in the category given by the filter <filt>.

If <filt> is not given it defaults to `IsPermGroup',
and the returned group is the action on lines of the underlying vector
space.




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Conjugacy Classes in Classical Groups}

\indextt{ConjugacyClasses!for linear  groups}
For  general  and   special  linear  groups  (see~"GeneralLinearGroup"
and~"SpecialLinearGroup") {\GAP}  has an efficient method  to generate
representatives  of  the conjugacy  classes.  This  uses results  from
linear algebra on normal forms of matrices. If you know how to do this
for other types of classical groups, please, tell us.

\beginexample
gap> g := SL(4,9);
SL(4,9)
gap> NrConjugacyClasses(g);
861
gap> cl := ConjugacyClasses(g);;
gap> Length(cl);
861
\endexample

\>NrConjugacyClassesGL( <n>, <q> ) F
\>NrConjugacyClassesGU( <n>, <q> ) F
\>NrConjugacyClassesSL( <n>, <q> ) F
\>NrConjugacyClassesSU( <n>, <q> ) F
\>NrConjugacyClassesPGL( <n>, <q> ) F
\>NrConjugacyClassesPGU( <n>, <q> ) F
\>NrConjugacyClassesPSL( <n>, <q> ) F
\>NrConjugacyClassesPSU( <n>, <q> ) F
\>NrConjugacyClassesSLIsogeneous( <n>, <q>, <f> ) F
\>NrConjugacyClassesSUIsogeneous( <n>, <q>, <f> ) F

The first of  these functions compute for given $<n>  \in N$ and prime
power $<q>$  the number of  conjugacy classes in the  classical groups
$GL( <n>, <q>  )$, $GU( <n>, <q>  )$, $SL( <n>, <q> )$,  $SU( <n>, <q>
)$, $PGL(  <n>, <q> )$,  $PGU( <n>, <q> )$,  $PSL( <n>, <q>  )$, $PSL(
<n>, <q> )$, respectively. (See also "ConjugacyClasses!attribute"  and
Section~"Classical Groups".)

For  each  divisor  $<f>$ of  $<n>$  there  is  a  group of  Lie  type
with  the same  order  as $SL(  <n>,  <q> )$,  such  that its  derived
subgroup  modulo  its center  is  isomorphic  to  $PSL( <n>,  <q>  )$.
The  various  such  groups  with  fixed $<n>$  and  $<q>$  are  called
*isogeneous*. (Depending  on congruence conditions on  $<q>$ and $<n>$
several of  these groups  may actually  be isomorphic.)  The  function
`NrConjugacyClassesSLIsogeneous'  computes  the  number  of  conjugacy
classes in this group. The extreme cases  $<f> = 1$ and $<f> = n$ lead
to the groups $SL( <n>, <q> )$ and $PGL( <n>, <q> )$, respectively.

The function `NrConjugacyClassesSUIsogeneous' is the analogous one for
the corresponding unitary groups.

The  formulae   for  the  number   of  conjugacy  classes   are  taken
from~\cite{Mac81}.


\beginexample
gap> NrConjugacyClassesGL(24,27);
22528399544939174406067288580609952
gap> NrConjugacyClassesPSU(19,17);
15052300411163848367708
gap> NrConjugacyClasses(SL(16,16));
1229782938228219920
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Constructors for Basic Groups}

All functions described in the previous sections call constructor operations
to do the work.
The names of the constructors are obtained from the names of the functions
by appending `Cons', so for example `CyclicGroup' calls the constructor

\){\fmark CyclicGroupCons( <cat>, <n> )} O

The first argument <cat> for each method of this constructor must be
the category for which the method is installed.
For example the method for constructing a cyclic permutation group
is installed as follows (see~"prg:InstallMethod" in ``Programming in {\GAP}''
for the meaning of the arguments of `InstallMethod').
\begintt
InstallMethod( CyclicGroupCons,
    "regular perm group",
    true,
    [ IsPermGroup and IsRegularProp and IsFinite, IsInt and IsPosRat ], 0,
    function( filter, n )

    ...

    end );
\endtt


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Selection Functions}

\indextt{AllPrimitiveGroups}\indextt{AllTransitiveGroups}
\>`All<Library>Groups( <fun1>, <val1>, ... )'{AllLibraryGroups}%
@{`All\noexpand<Library>Groups'}

For a number  of  the  group  libraries  two  *selection  functions*  are
provided. Each `All<Library>Groups' selection  function  permits  one  to
select *all* groups from the library <Library> that have a given  set  of
properties.
%The name of the selection  functions always begins  with `All' and always
%ends with `Groups'. In between is a  name that hints at the nature of the
%group library. 
Currently, the library selection functions provided, of  this  type,  are
`AllSmallGroups', `AllIrreducibleSolvableGroups',  `AllTransitiveGroups',
and `AllPrimitiveGroups'. Corresponding to  each  of  these  there  is  a
`One<Library>Group' function  (see~"OneLibraryGroup")  which  returns  at
most one group.

These functions take an arbitrary number of pairs (but at least one pair)
of arguments. The first argument in such a pair is a function that can be
applied to the groups in the library, and the second argument is either a
single value that this function must return in order to have  this  group
included in the selection, or a list of such  values.  For  the  function
`AllSmallGroups' the first such function must be `Size', and, unlike  the
other library selection functions,  it  supports  an  alternative  syntax
where   `Size'   is    omitted    (see~"AllSmallGroups").    Also,    see
"AllIrreducibleSolvableGroups",     for     details     pertaining     to
`AllIrreducibleSolvableGroups'.

For an example, let us consider the selection function for the library of
transitive  groups  (also  see~"Transitive  permutation   groups").   The
command,

%notest
\beginexample
gap> AllTransitiveGroups(NrMovedPoints,[10..15],
>                        Size,         [1..100],
>                        IsAbelian,    false    );
\endexample

returns a list of all transitive groups with degree between 10 and 15 and
size less than 100 that are not abelian.

Thus  the `AllTransitiveGroups'  behaves  as if   it was implemented  by a
function similar to the one defined below, where `TransitiveGroupsList' is a
list of all transitive groups.  (Note that in  the definition below we assume
for simplicity that `AllTransitiveGroups' accepts exactly 4 arguments.  It is
of course  obvious how to change this  definition so that the function would
accept a variable number of arguments.)

\begintt
AllTransitiveGroups := function( fun1, val1, fun2, val2 )
local    groups, g, i;
  groups := [];
  for i  in [ 1 .. Length( TransitiveGroupsList ) ] do
    g := TransitiveGroupsList[i];
    if      fun1(g) = val1  or IsList(val1) and fun1(g) in val1
        and fun2(g) = val2  or IsList(val2) and fun2(g) in val2
     then
      Add( groups, g );
    fi;
  od;
  return groups;
end;
\endtt
Note that the real  selection functions are considerably  more difficult,
to improve the efficiency. Most  important, each recognizes a certain set
of properties which are precomputed for the library without having to
compute them anew for each group. This will substantially speed up the
selection process.
In the description of each library we will
list the properties that are stored for this library.

\indextt{OnePrimitiveGroup}\indextt{OneTransitiveGroup}
\>`One<Library>Group( <fun1>, <val1>, ... )'{OneLibraryGroup}%
@{`One\noexpand<Library>Group'}

% If you  do not want  all groups with the  prescribed properties, but only
% one example, you should call the *example function*. It returns `fail' if
% no such group exists in the library.
%
% The following sections describing a particular group library mention only
% the *extraction   function*, by which  you  address a group   via (1)~its
% degree  or   size    (or for  matrix   groups  its    dimension  and  its
% characteristic) and  (2)~its  number  in  the list  of all   groups  with
% property~(1).

For each `All<Library>Groups' function (see~"AllLibraryGroups") there  is
a  corresponding  function  `One<Library>Group'  on  exactly   the   same
arguments,        i.e.\        there         are         `OneSmallGroup',
`OneIrreducibleSolvableGroup',         `OneTransitiveGroup',          and
`OnePrimitiveGroup'. Each function simply returns the  *first*  group  in
the library (in the stored order) that  has  the  prescribed  properties,
instead of *all* such groups. It returns `fail' if no such  group  exists
in the library.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Transitive Permutation Groups}

The transitive groups library currently contains representatives for all
transitive permutation groups of degree at most  30.
Two permutations groups of the same degree are considered to be
equivalent, if there is a renumbering of points, which maps one group into
the other one.
In other words, if they lie in the same conjugacy class under operation
of the full symmetric group by conjugation.

\>TransitiveGroup( <deg>, <nr> ) F

returns the <nr>-th transitive  group of degree <deg>.  Both  <deg> and
<nr> must be  positive integers. The transitive groups of equal  degree
are  sorted with  respect to   their  size, so for  example
`TransitiveGroup(  <deg>, 1 )' is a  transitive group  of degree and
size <deg>, e.g, the cyclic  group  of size <deg>,   if <deg> is a
prime.

\>NrTransitiveGroups( <deg> ) F

returns the number of transitive groups of degree <deg> stored in the
library of transitive groups. The function returns `fail' if <deg> is
beyond the range of the library.


The selection functions (see~"Selection functions") for the transitive
groups library are `AllTransitiveGroups' and `OneTransitiveGroup'. They
obtain the following properties from the database without having to compute
them anew:

`NrMovedPoints', `Size',   `Transitivity', and `IsPrimitive'.

This library was computed by  Gregory Butler, John McKay, Gordon Royle
and Alexander Hulpke.  The list of transitive  groups up  to degree 11
was published in \cite{BM83},  the list of degree  12 was published in
\cite{Roy87}, degree 14 and  15 were published in  \cite{Butler93} and
degrees 16--30 were published in \cite{Hulpke96} and \cite{HulpkeTG}.
(Groups of prime degree of course are
primitive and were known long before.)

The arrangement and the names of the groups of degree up to 15 is the same
as given in \cite{ConwayHulpkeMcKay98}. With the exception of the symmetric
and alternating group (which are represented as `SymmetricGroup' and
`AlternatingGroup') the generators for these groups also conform to this
paper with the only difference that 0 (which is not permitted in {\GAP} for
permutations to act on) is always replaced by the degree.

\beginexample
gap> TransitiveGroup(10,22);
S(5)[x]2
gap> l:=AllTransitiveGroups(NrMovedPoints,12,Size,1440,IsSolvable,false);
[ S(6)[x]2, M_10.2(12)=A_6.E_4(12)=[S_6[1/720]{M_10}S_6]2 ]
gap> List(l,IsSolvable);
[ false, false ]
\endexample

\>TransitiveIdentification( <G> ) A

Let <G> be a permutation group, acting transitively on a set  of up to 30
points.  Then `TransitiveIdentification' will return the position of this
group in the transitive  groups library.  This means,  if <G> acts on
$m$ points and    `TransitiveIdentification'  returns $n$,  then <G>   is
permutation isomorphic to the group `TransitiveGroup(m,n)'.

Note: The points moved do *not* need to be [1..<n>], the group
$\langle (2,3,4),(2,3)\rangle$ is considered to be transitive on 3
points. If the group has several orbits on the points moved by it the
result of `TransitiveIdentification' is undefined.


\beginexample
gap> TransitiveIdentification(Group((1,2),(1,2,3)));
2
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Small Groups}

The Small Groups library gives access to all groups of certain ``small''
orders. The groups are sorted by their orders and they are listed up to
isomorphism; that is, for each of the available orders a complete and
irredundant list of isomorphism type representatives of groups is given.
Currently, the library contains the following groups:
\beginlist%unordered
  \item{$\bullet$} those of order at most 2000 except 1024
                   \qquad ($423\;164\;062$ groups);
  \item{$\bullet$} those of cubefree order at most 50 000
                   \qquad ($395 \; 703$ groups);
  \item{$\bullet$} those of order $p^n$ for $n \leq 6$ and all primes $p$ 
  \item{$\bullet$} those of order $q^n \cdot p$ for $q^n$ dividing $2^8$, 
                   $3^6$, $5^5$ or $7^4$ and all primes $p$ with $p \neq q$;
  \item{$\bullet$} those of squarefree order;
  \item{$\bullet$} those whose order factorises into at most 3 primes.
\endlist
The first two items in this list cover an explicit range of orders; the 
last four provide access to infinite families of groups having orders of 
certain types.

The library also has an identification function: it returns the library 
number of a given group. This function determines library numbers using
invariants of groups. The function is available for all orders in the 
library except 512, 1536, $p^6$ for $p > 3$ and $p^5$ for $p > 5$.

The library is organised in 10 layers. Each layer contains the groups of
certain orders and their corresponding group identification routines. It
is possible to install the first $n$ layers of the group library and the
first $m$ layers of the group identification for each $1 \leq m \leq n
\leq 10$. This might be useful to save disk space. There is an extensive
`README' file for the Small Groups library available in the `small' directory
of the {\GAP} distribution containing detailed information on the layers.
A brief description of the layers is given here:
\beginlist%ordered
   \item{(1)} the groups whose order factorises into at most 3 primes.
   \item{(2)} the remaining groups of order at most 1000 except 512 and 768.
   \item{(3)} the remaining groups of order $2^n * p$ with $n \leq 8$ and
              $p$ an odd prime.
   \item{(4)} the remaining groups of order $5^5$, $7^4$ and of order 
              $q^n \cdot p$ for $q^n$ dividing $3^6$, $5^5$ or $7^4$ and 
              $p \neq q$ a prime.
   \item{(5)} the remaining groups of order at most 2000 except 1024,
              1152, 1536 and 1920.
   \item{(6)} the groups of orders 1152 and 1920.
   \item{(7)} the groups of order 512.
   \item{(8)} the groups of order 1536.
   \item{(9)} the remaining groups of order $p^n$ for $4 \leq n \leq 6$.
   \item{(10)} the remaining groups of cubefree order at most 50 000 and
               of squarefree order.
\endlist

The data in this library has been carefully checked and cross-checked.
It is believed to be reliable. However, no absolute guarantees are given
and users should, as always, make their own checks in critical cases.

The data occupies about 30 MB (storing over 400 million groups in about
200 megabits). The group identification occupies about 47 MB of which
18 MB is used for the groups in layer (6). More information on the Small 
Groups library can be found on
\URL{http://www.tu-bs.de/~hubesche/small.html}

This library has been constructed by Hans Ulrich Besche, Bettina Eick and 
E.~A.~O'Brien. A survey on this topic and an account of the history of 
group constructions can be found in \cite{BEO01}. Further detailed 
information on the construction of this library is available in \cite{New77}, 
\cite{OBr90}, \cite{OBr91}, \cite{BescheEick98}, \cite{BescheEick1000}, 
\cite{BescheEick768}, \cite{BEO00}, \cite{EOB99}, \cite{EOB98}, \cite{NOV04}, 
\cite{Gir03}, \cite{DEi05}.
 
\atindex{TwoGroup library}{@\noexpand`TwoGroup' library}
\atindex{ThreeGroup library}{@\noexpand`ThreeGroup' library}
The Small Groups library incorporates the {\GAP}~3 libraries `TwoGroup' and
`ThreeGroup'. The data from these libraries was directly included into the
Small Groups library, and the ordering there was preserved. The Small
Groups library replaces the Gap 3 library of solvable groups of order at
most 100. However, both the organisation and data descriptions of these
groups has changed in the Small Groups library.

\>SmallGroup( <order>, <i> ) F
\>SmallGroup( [<order>, <i>] ) F

returns the <i>-th group of order <order> in the catalogue. If the group
is solvable, it will be given as a PcGroup; otherwise it will be given as
a permutation group. If the groups of order <order> are not installed,
the function reports an error and enters a break loop.

\>AllSmallGroups( <arg> ) F

returns all groups with certain properties as specified by <arg>.
If <arg> is a number $n$, then this function returns all groups of order
$n$. However, the function can also take several arguments which then
must be organized in pairs `function' and `value'. In this case the first
function must be `Size' and the first value an order or a range of orders.
If value is a list then it is considered a list of possible function
values to include. 
The function returns those groups of the specified orders having those
properties specified by the remaining functions and their values.

Precomputed information is stored for the properties `IsAbelian', 
`IsNilpotentGroup', `IsSupersolvableGroup', `IsSolvableGroup', 
`RankPGroup', `PClassPGroup', `LGLength', `FrattinifactorSize' and 
`FrattinifactorId' for the groups of order at most $2000$ which have 
more than three prime factors, except those of order $512$, $768$, 
$1024$, $1152$, $1536$, $1920$ and those of order $p^n \cdot q > 1000$ 
with $n > 2$. 


\>OneSmallGroup( <arg> ) F

returns one group with certain properties as specified by <arg>.
The permitted arguments are those supported by `AllSmallGroups'.


\>NumberSmallGroups( <order> ) F

returns the number of groups of order <order>.

\>IdSmallGroup( <G> ) A
\>IdGroup( <G> ) A

returns the library number of <G>; that is, the function returns a pair
`[<order>, <i>]' where <G> is isomorphic to `SmallGroup( <order>, <i> )'.

\>IdsOfAllSmallGroups( <arg> ) F

similar to `AllSmallGroups' but returns ids instead of groups. This may
prevent workspace overflows, if a large number of groups are expected in 
the output.

\>IdGap3SolvableGroup( <G> ) A
\>Gap3CatalogueIdGroup( <G> ) A

returns the catalogue number of <G> in the GAP 3 catalogue of solvable
groups; that is, the function returns a pair `[<order>, <i>]' meaning that
<G> is isomorphic to the group `SolvableGroup( <order>, <i> )' in GAP 3.

\>SmallGroupsInformation( <order> ) F

prints information on the groups of the specified order.

\>UnloadSmallGroupsData( ) F

GAP loads all necessary data from the library automatically, but it does 
not delete the data from the workspace again. Usually, this will be not 
necessary, since the data is stored in a compressed format. However, if 
a large number of groups from the library have been loaded, then the user 
might wish to remove the data from the workspace and this can be done by 
the above function call.


\beginexample
gap> G := SmallGroup( 768, 1000000 );
<pc group of size 768 with 9 generators>
gap> G := SmallGroup( [768, 1000000] );
<pc group of size 768 with 9 generators>
\endexample

\beginexample
gap> AllSmallGroups( 6 );
[ <pc group of size 6 with 2 generators>, 
  <pc group of size 6 with 2 generators> ]
gap> AllSmallGroups( Size, 120, IsSolvableGroup, false );
[ Group([ (1,2,4,8)(3,6,9,5)(7,12,13,17)(10,14,11,15)(16,20,21,24)(18,22,19,
        23), (1,3,7)(2,5,10)(4,9,13)(6,11,8)(12,16,20)(14,18,22)(15,19,23)(17,
        21,24) ]), Group([ (1,2,3,4,5), (1,2) ]), 
  Group([ (1,2,3,5,4), (1,3)(2,4)(6,7) ]) ]
\endexample

\beginexample
gap> G := OneSmallGroup( 120, IsNilpotentGroup, false );
<pc group of size 120 with 5 generators>
gap> IdSmallGroup(G);
[ 120, 1 ]
gap> G := OneSmallGroup( Size, [1..1000], IsSolvableGroup, false );
Group([ (1,2,3,4,5), (1,2,3) ])
gap> IdSmallGroup(G);
[ 60, 5 ]
gap> UnloadSmallGroupsData();
\endexample

\beginexample
gap> IdSmallGroup( GL( 2,3 ) );
[ 48, 29 ]
gap> IdSmallGroup( Group( (1,2,3,4),(4,5) ) );
[ 120, 34 ]
gap> IdsOfAllSmallGroups( Size, 60, IsSupersolvableGroup, true );
[ [ 60, 1 ], [ 60, 2 ], [ 60, 3 ], [ 60, 4 ], [ 60, 6 ], [ 60, 7 ], 
  [ 60, 8 ], [ 60, 10 ], [ 60, 11 ], [ 60, 12 ], [ 60, 13 ] ]
\endexample

\beginexample
gap> NumberSmallGroups( 512 );
10494213
gap> NumberSmallGroups( 2^8 * 23 );
1083472
\endexample

%notest
\beginexample
gap> NumberSmallGroups( 2^9 * 23 );
Error, the library of groups of size 11776 is not available called from
<function>( <arguments> ) called from read-eval-loop
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue
brk> quit;
gap> 
\endexample

\beginexample
gap> SmallGroupsInformation( 32 );

  There are 51 groups of order 32.
  They are sorted by their ranks. 
     1 is cyclic. 
     2 - 20 have rank 2.
     21 - 44 have rank 3.
     45 - 50 have rank 4.
     51 is elementary abelian. 

  For the selection functions the values of the following attributes 
  are precomputed and stored:
     IsAbelian, PClassPGroup, RankPGroup, FrattinifactorSize and 
     FrattinifactorId. 

  This size belongs to layer 2 of the SmallGroups library. 
  IdSmallGroup is available for this size. 
 
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Finite Perfect Groups}

\index{perfect groups}
The {\GAP} library of finite  perfect groups provides, up to isomorphism,
a list of all perfect groups whose sizes are less than  $10^6$  excluding
the following sizes:
\beginlist%unordered
  \item{$\bullet$}
      For $n = 61440$, 122880, 172032, 245760, 344064, 491520, 688128, or
      983040,  the perfect groups  of size  $n$  have not completely been
      determined yet.  The library  neither provides  the number of these
      groups nor the groups themselves.
  \item{$\bullet$}
      For  $n = 86016$,  368640,  or  737280,  the library  does not  yet
      contain  the perfect groups  of size  $n$,  it  only provides their
      numbers which are 52, 46, and 54, respectively.
\endlist

Except for these eleven sizes, the list of altogether 1097 perfect groups
in the  library is complete.  It relies  on results of  Derek~F. Holt and
Wilhelm Plesken which  are published in their  book    ``Perfect Groups''
\cite{HP89}. Moreover,   they     have  supplied us    with    files with
presentations of 488 of the groups. In terms of  these, the remaining 607
nontrivial groups in the library can be described as 276 direct products,
107  central   products, and 224  subdirect  products.  They are computed
automatically by suitable {\GAP} functions whenever they are needed.  Two
additional groups omitted from the book ``Perfect Groups'' have also been
included.

We are grateful to Derek Holt and Wilhelm Plesken for making their groups
available to the {\GAP} community  by contributing their files. It should
be noted that  their book contains a  lot of further information for many
of the library groups.  So we would like  to recommend  it to any  {\GAP}
user who is interested in the groups.

The library has been brought into {\GAP} format by Volkmar Felsch.

\>SizesPerfectGroups( ) F



\>PerfectGroup( [<filt>, ]<size>[, <n>] ) F
\>PerfectGroup( [<filt>, ]<sizenumberpair> ) F

returns a group which is isomorphic to the library group specified
by the size number `[ <size>, <n> ]'  or   by the  two  separate
arguments <size> and  <n>,  assuming a default   value  of $<n> = 1$.
The optional argument <filt> defines the filter in which the group is
returned.
Possible filters so far are `IsPermGroup' and `IsSubgroupFpGroup'.
In the latter case, the  generators and relators used coincide with those
given in~\cite{HP89}.


\beginexample
gap> G := PerfectGroup(IsPermGroup,6048,1);
U3(3)
\endexample

As  all groups are stored  by presentations, a permutation representation
is obtained by coset enumeration. Note that some of the library groups do
not have a   faithful   permutation  representation  of small     degree.
Computations in these groups may be rather time consuming.
\beginexample
gap> G:=PerfectGroup(IsPermGroup,823080,2);
A5 2^1 19^2 C 19^1
gap> NrMovedPoints(G);
6859
\endexample

\>PerfectIdentification( <G> ) A

This attribute is set for all groups obtained from the perfect groups
library and has the value `[<size>,<nr>]' if the group is obtained with
these parameters from the library.



\>NumberPerfectGroups( <size> ) F

returns the number of non-isomorphic perfect groups of size <size> for
each positive integer  <size> up to $10^6$ except for the eight  sizes
listed at the beginning  of  this section for  which the number is not
yet known. For these values as well as for any argument out of range it
returns `fail'.


\>NumberPerfectLibraryGroups( <size> ) F

returns the number of perfect groups of size <size> which are available
in the  library of finite perfect groups. (The purpose  of the function
is  to provide a simple way  to formulate a loop over all library groups
of a given size.)



\>SizeNumbersPerfectGroups( <factor1>, <factor2>, ... ) F

`SizeNumbersPerfectGroups' returns a list of pairs, each entry consisting
of a group order and the number of those groups in the library of perfect
groups that contain the specified factors <factor1>, <factor2>, ...
among their composition factors.

Each argument must either be the name of a simple group or an integer
which stands for the product of the sizes of one or more cyclic factors.
(In fact, the function replaces all integers among the arguments
by their product.)

The following text strings are accepted as simple group names.
\beginlist%unordered
  \item{$\bullet$} `A<n>' or  `A(<n>)' for the  alternating groups $A_n$,
    $5\leq n\leq9$, for example `A5' or `A(6)'.
  \item{$\bullet$}  `L<n>(<q>)'   or  `L(<n>,<q>)' for  $PSL(n,q)$, where
    $n\in\{2,3\}$ and $q$ a prime power, ranging
    \itemitem{$\circ$}%unordered
                       for $n=2$ from 4 to 125
    \itemitem{$\circ$} for $n=3$ from 2 to 5
  \item{$\bullet$} `U<n>(<q>)'  or  `U(<n>,<q>)' for   $PSU(n,q)$,  where
    $n\in\{3,4\}$ and $q$ a prime power, ranging
    \itemitem{$\circ$}%unordered
                       for $n=3$ from 3 to 5
    \itemitem{$\circ$} for $n=4$ from 2 to 2
  \item{$\bullet$} `Sp4(4)' or `S(4,4)' for the symplectic group $S(4,4)$,
  \item{$\bullet$} `Sz(8)' for the Suzuki group $Sz(8)$,
  \item{$\bullet$} `M<n>'  or `M(<n>)' for  the  Mathieu groups $M_{11}$,
    $M_{12}$, and $M_{22}$, and
  \item{$\bullet$} `J<n>' or `J(<n>)'   for  the Janko groups  $J_1$  and
    $J_2$.
\endlist

Note  that, for  most  of the  groups,   the  preceding list  offers  two
different  names in order  to  be consistent  with the  notation used  in
\cite{HP89}  as     well  as     with    the  notation    used    in  the
`DisplayCompositionSeries' command of {\GAP}.   However, as the names are
compared  as text strings, you are  restricted to  the above choice. Even
expressions like `L2(2^5)' are not accepted.

As the use of the  term $PSU(n,q)$ is  not  unique in the literature,  we
mention that in this library it denotes the factor  group of $SU(n,q)$ by
its centre, where $SU(n,q)$ is  the group of all $n  \times n$ unitary
matrices  with entries in $GF(q^2)$ and determinant 1.

The purpose  of the function is  to provide a  simple way to  formulate a
loop over all library groups which contain certain composition factors.



\>DisplayInformationPerfectGroups( <size> ) F
\>DisplayInformationPerfectGroups( <size>, <n> ) F
\>DisplayInformationPerfectGroups( [ <size>, <n> ] ) F

`DisplayInformationPerfectGroups' displays some invariants of the <n>-th
group of order <size> from the perfect groups library.

If no value of <n> has been specified, the invariants will be displayed
for all groups of size <size> available in the library.
The information provided for $G$ includes the following items:
\beginlist%unordered
  \item{$\bullet$}
      a headline containing the size number `[ <size>, <n> ]' of $G$
      in the form `<size>.<n>' (the suffix `.<n>' will be suppressed
      if, up to isomorphism, $G$ is the only perfect group of order
      <size>),
  \item{$\bullet$} a message if $G$ is simple  or quasisimple, i.e.,
      if the factor group of $G$ by its centre is simple,
  \item{$\bullet$} the ``description'' of  the structure of  $G$ as it is
    given by Holt and Plesken in~\cite{HP89} (see below),
  \item{$\bullet$} the size of  the centre of $G$  (suppressed, if $G$ is
    simple),
  \item{$\bullet$} the prime decomposition of the size of $G$,
  \item{$\bullet$} orbit sizes for  a faithful permutation representation
    of $G$ which is provided by the library (see below),
  \item{$\bullet$} a reference to each occurrence of $G$ in the tables of
    section 5.3    of  \cite{HP89}. Each  of   these  references
    consists of a class number and an internal number $(i,j)$ under which
    $G$ is listed in that class. For some groups, there  is more than one
    reference because these groups belong to more than one of the classes
    in the book.
\endlist



\beginexample
gap> DisplayInformationPerfectGroups( 30720, 3 );
#I Perfect group 30720:  A5 ( 2^4 E N 2^1 E 2^4 ) A
#I   size = 2^11*3*5  orbit size = 240
#I   Holt-Plesken class 1 (9,3)
gap> DisplayInformationPerfectGroups( 30720, 6 );
#I Perfect group 30720:  A5 ( 2^4 x 2^4 ) C N 2^1
#I   centre = 2  size = 2^11*3*5  orbit size = 384
#I   Holt-Plesken class 1 (9,6)
gap> DisplayInformationPerfectGroups( Factorial( 8 ) / 2 );
#I Perfect group 20160.1:  A5 x L3(2) 2^1
#I   centre = 2  size = 2^6*3^2*5*7  orbit sizes = 5 + 16
#I   Holt-Plesken class 31 (1,1) (occurs also in class 32)
#I Perfect group 20160.2:  A5 2^1 x L3(2)
#I   centre = 2  size = 2^6*3^2*5*7  orbit sizes = 7 + 24
#I   Holt-Plesken class 31 (1,2) (occurs also in class 32)
#I Perfect group 20160.3:  ( A5 x L3(2) ) 2^1
#I   centre = 2  size = 2^6*3^2*5*7  orbit size = 192
#I   Holt-Plesken class 31 (1,3)
#I Perfect group 20160.4:  simple group  A8
#I   size = 2^6*3^2*5*7  orbit size = 8
#I   Holt-Plesken class 26 (0,1)
#I Perfect group 20160.5:  simple group  L3(4)
#I   size = 2^6*3^2*5*7  orbit size = 21
#I   Holt-Plesken class 27 (0,1)
\endexample

For any library  group  $G$, the library    files do not  only provide  a
presentation, but, in  addition, a list  of  one or more subgroups  $S_1,
\ldots,  S_r$  of   $G$ such   that   there is  a   faithful  permutation
representation  of $G$ of degree  $\sum_{i=1}^{r} [G:S_i]$ on the set $\{
S_i g \mid 1 \leq i \leq  r, \, g \in  G \}$ of  the cosets of the $S_i$.
This allows one to construct the groups as permutation groups. The
`DisplayInformationPerfectGroups'  function  displays  only the available
degree. The message
\begintt
orbit size = 8
\endtt

in the above example means  that the available permutation representation
is transitive and of degree 8, whereas the message
\begintt
orbit sizes = 5 + 16
\endtt
means that a nontransitive  permutation representation is available which
acts on two orbits of size 5 and 16 respectively.

The  notation used in  the ``description''  of  a  group is explained  in
section 5.1.2 of \cite{HP89}. We quote the respective page from there:

{\advance\leftskip by\manindent \advance\rightskip by\manindent%
Within a class $Q\,\#\,p$, an isomorphism type of groups will be  denoted
by an ordered pair of integers $(r,n)$, where $r \geq 0$  and  $n  >  0$.
More precisely, the isomorphism types in $Q \# p$ of order $p^r |Q|$ will
be denoted by $(r,1), (r,2), (r,3), \ldots\,$. Thus $Q$ will  always  get
the size number $(0,1)$.

In addition to the symbol $(r,n)$, the groups in $Q\,\#\,p$ will also  be
given a more descriptive name. The purpose of this is to provide  a  very
rough idea of the structure of the group. The names are  derived  in  the
following manner. First of all, the isomorphism  classes  of  irreducible
$F_pQ$-modules $M$ with $|Q|.|M| \leq 10^6$, where $F_p$ is the field  of
order $p$, are assigned symbols. These will either be simply $p^x$, where
$x$ is the dimension of the  module,  or,  if  there  is  more  than  one
isomorphism class of irreducible modules having the same dimension,  they
will be denoted by $p^x, p^{x^\prime}$, etc. The  one-dimensional  module
with trivial $Q$-action will therefore be denoted by $p^1$. These symbols
will be listed under the description of  $Q$.  The  group  name  consists
essentially of a list of the composition factors working from the top  of
the group downwards; hence it always starts with the name of $Q$  itself.
(This convention is the  most  convenient  in  our  context,  but  it  is
different from that adopted in the ATLAS \cite{CCN85}, for example, where
composition factors are listed in the  reverse  order.  For  example,  we
denote a group isomorphic to $SL(2,5)$ by $A_5 2^1$ rather than $2.A_5$.)

Some  other symbols are used  in the name, in order  to give some idea of
the   relationship  between these    composition  factors, and  splitting
properties. We shall now list these additional symbols.

\beginlist
\item{$\times$}  between  two  factors   denotes   a  direct  product  of
      $F_pQ$-modules or groups.

\item{C} (for ``commutator'') between two factors  means  that the second
      lies in the commutator subgroup of the first.  Similarly, a segment
      of the form  $(f_1 \! \times \! f_2) {\sl C} f_3$  would mean  that
      the factors $f_1$ and $f_2$  commute modulo $f_3$ and $f_3$ lies in
      $[f_1,f_2]$.

\item{A} (for ``abelian'') between two factors  indicates that the second
      is  in the  $p$th  power  (but not the commutator subgroup)  of the
      first.   ``A''   may  also   follow  the  factors,   if  bracketed.

\item{E} (for ``elementary abelian'') between two factors  indicates that
      together   they  generate  an  elementary  abelian  group   (modulo
      subsequent factors), but that the resulting $F_pQ$-module extension
      does not split.

\item{N}  (for ``nonsplit'') before  a  factor  indicates  that  $Q$  (or
      possibly its covering group)  splits down as far at this factor but
      not over the factor itself.  So  ``$Q f_1 {\sl N} f_2$'' means that
      the normal subgroup  $f_1f_2$  of the group  has no complement but,
      modulo $f_2$, $f_1$, does have a complement.

\endlist

Brackets have their obvious meaning. Summarizing, we have:

\beginlist
\item{$\times$} = direct product;

\item{C} = commutator subgroup;

\item{A} = abelian;

\item{E} = elementary abelian; and

\item{N} = nonsplit.

\endlist

Here are some examples.

\beginlist%ordered{i}
\item{(i)}  $A_5 (2^4 {\sl E} 2^1 {\sl E} 2^4) {\sl A}$  means  that  the
      pairs  $2^4 {\sl E} 2^1$  and $2^1 {\sl E} 2^4$ are both elementary
      abelian of exponent 4.

\item{(ii)}   $A_5 (2^4 {\sl E} 2^1 {\sl A}) {\sl C} 2^1$    means   that
      $O_2(G)$  is of  symplectic type  $2^{1+5}$,  with  Frattini factor
      group  of type   $2^4 {\sl E} 2^1$.   The   ``A''  after the  $2^1$
      indicates that $G$ has a  central cyclic subgroup $2^1 {\sl A} 2^1$
      of order 4.

\item{(iii)}     $L_3(2) ((2^1 {\sl E}) \! \times \! ({\sl N} 2^3 {\sl E}
      2^{3^\prime} {\sl A}) {\sl C}) 2^{3^\prime}$    means   that    the
      $2^{3^\prime}$ factor at the bottom lies in the commutator subgroup
      of the pair $2^3 {\sl E} 2^{3^\prime}$ in the middle, but the lower
      pair $2^{3^\prime} {\sl A} 2^{3^\prime}$  is abelian of exponent 4.
      There  is  also  a submodule  $2^1 {\sl E} 2^{3^\prime}$,  and  the
      covering group  $L_3(2) 2^1$  of  $L_3(2)$  does not split over the
      $2^3$  factor.  (Since $G$ is perfect,  it goes without saying that
      the extension $L_3(2) 2^1$ cannot split itself.)

\endlist

We  must  stress  that this  notation does   not  always succeed in being
precise  or even unambiguous, and the  reader is free to  ignore it if it
does not seem helpful.
\par}%

If such a group description has  been given in  the book for $G$ (and, in
fact, this is the case for  most of the library  groups), it is displayed
by the `DisplayInformationPerfectGroups' function. Otherwise the function
provides a less explicit  description  of  the  (in these cases   unique)
Holt-Plesken class to which $G$ belongs, together with a serial number if
this is necessary to make it unique.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Primitive Permutation Groups}

{\GAP} contains a library of primitive permutation groups which includes
the following permutation groups up to permutation isomorphism (i.e., up
to conjugacy  in the corresponding symmetric group)
\beginlist%unordered
  \item{$\bullet$} all  primitive  permutation groups of  degree $\<2500$,
    calculated in \cite{RoneyDougal05}
    in particular,
    \itemitem{$\circ$}%unordered
      the primitive permutation groups up to degree~50,
      calculated by C.~Sims,
    \itemitem{$\circ$} the primitive groups with insoluble socles of 
      degree $\<1000$ as calculated in \cite{DixonMortimer88},
    \itemitem{$\circ$} the solvable (hence affine) primitive permutation
      groups of degree $\<256$ as calculated by M.~Short \cite{Sho92},
    \itemitem{$\circ$} some insolvable affine primitive permutation groups
      of degree $\<256$ as calculated in \cite{Theissen97}.
    \itemitem{$\circ$} The solvable primitive groups of degree up to
      $999$ as calculated in  \cite{EickHoefling02}.
    \itemitem{$\circ$} The primitive groups of affine type of degree up 
      to $999$ as calculated in \cite{RoneyDougal02}.
\endlist

Not all groups are named, those which do have names use
ATLAS notation. Not all names are necessary unique!

The list given in \cite{RoneyDougal05} is believed to be complete,
correcting various omissions in \cite{DixonMortimer88}, \cite{Sho92}
and \cite{Theissen97}.

In detail, we guarantee the following properties for this and further
versions (but *not* versions which came before {\GAP}~4.2) of the library:

\beginlist%unordered
\item{$\bullet$} All groups in the library are primitive permutation
groups of the indicated degree.
\item{$\bullet$} The positions of the groups in the library are stable.
That is `PrimitiveGroup(<n>,<nr>)' will always give you a permutation
isomorphic group. Note however that we do not guarantee to keep the
chosen $S_n$-representative, the generating set or the name for 
eternity.
\item{$\bullet$} Different groups in the library are not conjugate in
$S_n$.
\item{$\bullet$} If a group in the library has a primitive subgroup with 
the same socle, this group is in the library as well.
\endlist

(Note that the arrangement of groups is not guaranteed to be in
increasing size, though it holds for many degrees.)


\>PrimitiveGroup( <deg>, <nr> ) F

returns the primitive permutation  group of degree <deg> with number <nr>
from the list. 

The arrangement of the groups differs from the arrangement of primitive
groups in the list of C.~Sims, which was used in {\GAP}~3. See
`SimsNo' ("SimsNo").


\>NrPrimitiveGroups( <deg> ) F

returns the number of primitive permutation groups of degree <deg> in the
library.



\beginexample
gap> NrPrimitiveGroups(25);
28
gap> PrimitiveGroup(25,19);
5^2:((Q(8):3)'4)
gap> PrimitiveGroup(25,20);
ASL(2, 5)
gap> PrimitiveGroup(25,22);
AGL(2, 5)
gap> PrimitiveGroup(25,23);
(A(5) x A(5)):2
\endexample

The selection functions (see~"Selection functions") for the primitive
groups library are `AllPrimitiveGroups' and `OnePrimitiveGroup'. They
obtain the following properties from the database without having to
compute them anew: 

`NrMovedPoints', `Size', `Transitivity', `ONanScottType',
`IsSimpleGroup', `IsSolvableGroup', and `SocleTypePrimitiveGroup'.

(Note, that for groups of degree up to 2499, O'Nan-Scott types 4a, 4b and
5 cannot occur.)


\>PrimitiveGroupsIterator( <attr1>, <val1>, <attr2>, <val2>, ... ) F

returns an iterator through
`AllPrimitiveGroups(<attr1>,<val1>,<attr2>,<val2>,...)' without creating
all these groups at the same time.



\>`COHORTS_PRIMITIVE_GROUPS' V

In \cite{DixonMortimer88} the primitive groups are sorted in
``cohorts'' according to their socle. For each degree, the variable
`COHORTS_PRIMITIVE_GROUPS' contains a list of the cohorts
for the primitive groups of this degree. Each cohort is represented by a
list of length 2, the first entry specifies the socle type (see
`SocleTypePrimitiveGroup', section~"SocleTypePrimitiveGroup"), the second
entry listing the index numbers of the groups in this degree.

For example in degree 49, we have four cohorts with socles $\F_7^2$,
$L_2(7)^2$, $A_7^2$ and $A_{49}$ respectively. the group
`PrimitiveGroup(49,36)', which is isomorphic to $(A_7\times A_7):2^2$, lies
in the third cohort with socle $(A_7\times A_7)$.

\beginexample
gap> COHORTS_PRIMITIVE_GROUPS[49];
[ [ rec( series := "Z", parameter := 7, width := 2 ), 
      [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 
          20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33 ] ], 
  [ rec( series := "L", parameter := [ 2, 7 ], width := 2 ), [ 34 ] ], 
  [ rec( series := "A", parameter := 7, width := 2 ), [ 35, 36, 37, 38 ] ], 
  [ rec( series := "A", parameter := 49, width := 1 ), [ 39, 40 ] ] ]
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Index numbers of primitive groups}

\>PrimitiveIdentification( <G> ) A

For a primitive permutation group for which an $S_n$-conjugate exists in
the library of primitive permutation groups (see~"Primitive Permutation
Groups"), this attribute returns the index position. That is <G> is
conjugate to
`PrimitiveGroup(NrMovedPoints(<G>),PrimitiveIdentification(<G>))'.

Methods only exist if the primitive groups library is installed.

Note: As this function uses the primitive groups library, the result is
only guaranteed to the same extent as this library. If it is incomplete,
`PrimitiveIdentification' might return an existing index number for a
group not in the library.


\beginexample
gap> PrimitiveIdentification(Group((1,2),(1,2,3)));
2
\endexample

\>SimsNo( <G> ) A

If <G> is a primitive group obtained by `PrimitiveGroup' (respectively one
of the selection functions) this attribute contains the number of the
isomorphic group in the original list of C.~Sims. (this is the
arrangement as it was used in {\GAP}~3.



\beginexample
gap> g:=PrimitiveGroup(25,2);
5^2:S(3)
gap> SimsNo(g);
3
\endexample

As mentioned in the previous section, the index numbers of primitive groups
in {\GAP} are guaranteed to remain stable. (Thus, missing groups will be
added to the library at the end of each degree.)
In particular, it is safe to refer to a primitive group of type <deg>,<nr>
in the {\GAP} library. 

The system `Magma' also provides a list of primitive groups
(see \cite{RoneyDougal02}). For historical
reasons, its indexing up to degree 999 
differs from the one used by {\GAP}. The
variable

\>`PRIMITIVE_INDICES_MAGMA' V

can be used to obtain this correspondence. The magma index number of
the {\GAP} group `PrimitiveGroup(<deg>,<nr>)' is stored in the entry
`PRIMITIVE_INDICES_MAGMA[<deg>][<nr>]', for degree at most 999.

Vice versa, the group of degree <deg> with `Magma' index number <nr> has the
{\GAP} index 

`Position(PRIMITIVE_INDICES_MAGMA[<deg>],<nr>)', in particular
it can be obtained by the {\GAP} command

`PrimitiveGroup(<deg>,Position(PRIMITIVE_INDICES_MAGMA[<deg>],<nr>));'

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Irreducible Solvable Matrix Groups}

\>IrreducibleSolvableGroupMS( <n>, <p>, <i> ) F

This function returns a representative of the <i>-th conjugacy class of
irreducible solvable subgroup of <GL(n,p)>, where <n> is an
integer $> 1$, <p> is a prime, and $<p>^{<n>} \< 256$.

The numbering of the representatives should be 
considered arbitrary. However, it is guaranteed that the <i>-th 
group on this list will lie in the same conjugacy class in all future
versions of {\GAP}, unless two (or more) groups on the list are discovered
to be duplicates, in which case `IrreducibleSolvableMatrixGroup' will
return `fail' for all but one of the duplicates. 

For values of <n>, <p>, and <i> admissible to  `IrreducibleSolvableGroup',
`IrreducibleSolvableMatrixGroup' returns a representative of the same
conjugacy class of subgroups of <GL(n,p)> as `IrreducibleSolvableGroup'.
Note that it currently adds two more groups (missing from the
original list by Mark Short) for $<n> = 2$, $<p> = 13$. 



\>NumberIrreducibleSolvableGroups( <n>, <p> ) F

This function returns the number of conjugacy classes of 
irreducible solvable subgroup of 
<GL(n,p)>. 



\>AllIrreducibleSolvableGroups( <func_1>, <val_1>, <func_2>, <val_2>, ... ) F

This function returns a list  of conjugacy class representatives <G> of
matrix groups over a prime field such that $<func_i>(G) = <val_i>$ or
$<func_i>(G) \in <val_i>$. The following possibilities for <func_i> 
are particularly efficient, because the values can be read off the
information in the data base: `DegreeOfMatrixGroup' (or
`Dimension' or `DimensionOfMatrixGroup') for the linear  degree,
`Characteristic' for the field characteristic, `Size',
`IsPrimitiveMatrixGroup' (or `IsLinearlyPrimitive'), and
`MinimalBlockDimension'.



\>OneIrreducibleSolvableGroup( <func1>, <val1>, <func2>, <val2>, ... ) F

This function returns one solvable subgroup <G> of a
matrix group over a prime field such that $<func_i>(G) = <val_i>$ or
$<func_i>(G) \in <val_i>$ for all <i>. The following possibilities
for <func_i>
are particularly efficient, because the values can be read off the
information in the data base: `DegreeOfMatrixGroup' (or
`Dimension' or `DimensionOfMatrixGroup') for the linear  degree,
`Characteristic' for the field characteristic, `Size',
`IsPrimitiveMatrixGroup' (or `IsLinearlyPrimitive'), and
`MinimalBlockDimension'.



\>`PrimitiveIndexIrreducibleSolvableGroup' V

This variable provides a way to get from irreducible solvable groups to
primitive groups and vice versa. For the group
<G>=`IrreducibleSolvableGroup( <n>, <p>, <k> )' and $d=p^n$, the entry
`PrimitiveIndexIrreducibleSolvableGroup[d][i]' gives the index number of
the semidirect product $p^n:G$ in the library of primitive groups.

Searching for an index `Position' in this list gives the translation in
the other direction.


\>IrreducibleSolvableGroup( <n>, <p>, <i> ) F

This function is obsolete, because for $<n> = 2$, $<p> = 13$, 
two groups were missing from the
underlying database. It has been replaced by the function
`IrreducibleSolvableGroupMS' (see
"IrreducibleSolvableGroupMS"). Please note that the latter
function does not guarantee any ordering of the groups in the database.
However, for values of <n>, <p>, and <i> admissible to
`IrreducibleSolvableGroup',
`IrreducibleSolvableGroupMS' returns a representative of the
same conjugacy class of subgroups of <GL(n,p)> as
`IrreducibleSolvableGroup' did before. 




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Irreducible Maximal Finite Integral Matrix Groups}

A   library of irreducible   maximal finite   integral  matrix groups  is
provided with {\GAP}. It  contains $\Q$-class representatives for  all of
these groups of dimension at  most 31, and $\Z$-class representatives for
those of dimension at most 11 or of dimension 13, 17, 19, or 23.

The  groups  provided  in this  library  have been  determined by Wilhelm
Plesken, partially as joint work with Michael Pohst, or by members of his
institute (Lehrstuhl B f{\accent127u}r    Mathematik, RWTH  Aachen).   In
particular, the data for the groups of dimensions  2 to 9 have been taken
from the output  of computer  calculations which  they performed in  1979
(see   \cite{PP77}, \cite{PP80}). The  $\Z$-class  representatives of the
groups  of  dimension  10 have  been  determined and    computed by Bernd
Souvignier (\cite{Sou94}),  and those of  dimensions 11, 13,  and 17 have
been  recomputed for this library from  the circulant Gram matrices given
in  \cite{Ple85}, using the  stand-alone  programs for the computation of
short vectors and Bravais groups which have  been developed in  Plesken's
institute. The $\Z$-class representatives of  the groups of dimensions 19
and  23 had already been  determined in  \cite{Ple85}.  Gabriele Nebe has
recomputed them  for us. Her  main contribution to this library, however,
is that she has determined and computed the $\Q$-class representatives of
the groups  of non-prime dimensions  between 12 and  24 and the groups of
dimensions  25  to  31   (see   \cite{PN95},  \cite{NP95},  \cite{Neb95},
\cite{Neb96}).

The library has been brought into {\GAP} format by Volkmar Felsch. He has
applied several {\GAP} routines  to check certain consistency of the data.
However, the  credit  and responsibility for  the lists   remain with the
authors. We are   grateful to Wilhelm Plesken,  Gabriele  Nebe, and Bernd
Souvignier for supplying their results to {\GAP}.

In the preceding  acknowledgement, we used  some notations that will also
be needed in the sequel. We first define these.

Any  integral matrix   group  $G$  of  dimension   $n$ is a  subgroup  of
$GL_n(\Z)$ as  well  as of  $GL_n(\Q)$  and hence lies in  some conjugacy
class of integral  matrix groups   under  $GL_n(\Z)$  and also in    some
conjugacy class of rational matrix  groups under $GL_n(\Q)$. As usual, we
call  these  classes    the  $\Z$-class   and the   $\Q$-class   of  $G$,
respectively.  Note that any conjugacy  class of subgroups of  $GL_n(\Q)$
contains at least one $\Z$-class of subgroups of $GL_n(\Z)$ and hence can
be considered as the $\Q$-class of some integral matrix group.

In  the context of  this library we are  only concerned with $\Z$-classes
and $\Q$-classes of subgroups   of $GL_n(\Z)$ which are irreducible   and
maximal   finite in $GL_n(\Z)$ (we   will call them *i.m.f.*~subgroups of
$GL_n(\Z)$).  We can distinguish two types of these groups:

First, there are  those  i.m.f.~subgroups  of $GL_n(\Z)$ which   are also
maximal  finite subgroups of $GL_n(\Q)$.  Let  us denote the set of their
$\Q$-classes by $Q_1(n)$. It is clear from the above remark that $Q_1(n)$
just consists of the $\Q$-classes of i.m.f.~subgroups of $GL_n(\Q)$.

Secondly, there is the set $Q_2(n)$ of the  $\Q$-classes of the remaining
i.m.f.~subgroups of $GL_n(\Z)$, i.e.,  of   those which are  not  maximal
finite subgroups of $GL_n(\Q)$. For any such group  $G$, say, there is at
least one class $C \in Q_1(n)$ such that $G$ is conjugate under $\Q$ to a
proper subgroup of some   group $H \in C$.   In  fact, the class $C$   is
uniquely determined for any group   $G$ occurring in the library  (though
there seems to be no  reason to assume that  this property should hold in
general).  Hence   we may   call   $C$  the *rational   i.m.f.~class*  of
$G$. Finally, we  will  denote the   number of  classes  in  $Q_1(n)$ and
$Q_2(n)$ by $q_1(n)$ and $q_2(n)$, respectively.

As an example, let us consider the case $n = 4$. There are 6 $\Z$-classes
of i.m.f.~subgroups  of $GL_4(\Z)$   with representative subgroups  $G_1,
\ldots,  G_6$ of isomorphism types  $G_1 \cong W(F_4)$, $G_2 \cong D_{12}
\wr C_2$, $G_3 \cong  G_4 \cong C_2 \times  S_5$, $G_5 \cong W(B_4)$, and
$G_6  \cong (D_{12}  ` Y   '  D_{12})   \!:\! C_2$.  The    corresponding
$\Q$-classes, $R_1, \ldots, R_6$, say, are pairwise different except that
$R_3$ coincides  with $R_4$.   The  groups $G_1$,  $G_2$, and  $G_3$  are
i.m.f.~subgroups of $GL_4(\Q)$, but $G_5$  and $G_6$ are not because they
are  conjugate under $GL_4(\Q)$ to proper  subgroups  of $G_1$ and $G_2$,
respectively.  So we  have $Q_1(4) = \{ R_1,  R_2, R_3 \}$,  $Q_2(4) = \{
R_5, R_6 \}$, $q_1(4) = 3$, and $q_2(4) = 2$.

The $q_1(n)$ $\Q$-classes   of i.m.f.~subgroups of  $GL_n(\Q)$  have been
determined  for each dimension  $n \leq 31$.   The current {\GAP} library
provides integral representative groups for all these classes.  Moreover,
all $\Z$-classes of i.m.f.~subgroups of $GL_n(\Z)$  are known for $n \leq
11$ and  for $n \in \{13,17,19,23\}$. For   these dimensions, the library
offers integral  representative  groups for all $\Q$-classes  in $Q_1(n)$
and $Q_2(n)$ as  well as  for   all $\Z$-classes  of i.m.f.~subgroups  of
$GL_n(\Z)$.

Any group $G$ of dimension $n$ given in the library is represented as the
automorphism group $G = {\rm Aut}(F,L) = \{ g \in GL_n(\Z) \mid Lg = L \;
{\rm and} \; g F g^{\rm  tr} = F \}$ of  a positive definite symmetric $n
\times n$ matrix $F \in \Z^{n \times n}$ on an $n$-dimensional lattice $L
\cong  \Z^{1 \times n}$    (for details see  e.g.   \cite{PN95}).  {\GAP}
provides for $G$ a list of matrix generators and the *Gram matrix* $F$.

The positive definite quadratic form defined by $F$ defines a *norm* $v F
v^{\rm tr}$ for each vector $v \in L$, and there is only  a finite set of
vectors of  minimal   norm.  These vectors are  often   simply called the
*short  vectors*.  Their set splits into  orbits under $G$, and $G$ being
irreducible  acts faithfully on  each  of these orbits by  multiplication
from the right.  {\GAP} provides for each  of these orbits the orbit size
and a representative vector.

Like most of the  other {\GAP} libraries,  the library of i.m.f.~integral
matrix   groups   supplies an   extraction   function,  `ImfMatrixGroup'.
However, as the  library involves only 525  different groups, there is no
need for a   selection or an  example function.  Instead,   there are two
functions, `ImfInvariants' and `DisplayImfInvariants', which provide some
$\Z$-class invariants   that can be extracted  from   the library without
actually constructing   the   representative    groups   themselves.  The
difference between these two functions  is  that the latter one  displays
the resulting data in some easily  readable format, whereas the first one
returns them as record components so that you can properly access them.

We shall give an individual description of each of the library functions,
but first we would like to insert a short remark  concerning their names:
Any  self-explaining name of  a  function  handling  *irreducible maximal
finite integral  matrix groups* would  have to include  this term in full
length and hence would grow extremely long.  Therefore we have decided to
use the abbreviation `Imf' instead in order to restrict the names to some
reasonable length.

The  first  three  functions can   be  used to formulate  loops  over the
classes.

\>ImfNumberQQClasses( <dim> ) F
\>ImfNumberQClasses( <dim> ) F
\>ImfNumberZClasses( <dim>, <q> ) F

`ImfNumberQQClasses' returns the number $q_1($<dim>$)$ of $\Q$-classes of
i.m.f.~rational matrix groups of dimension  <dim>. Valid values of  <dim>
are all positive integers up to 31.

Note: In order  to enable you to loop  just over the classes belonging to
$Q_1($<dim>$)$, we have  arranged  the list of $\Q$-classes  of dimension
<dim>  for any dimension  <dim>  in the  library such that,  whenever the
classes of $Q_2($<dim>$)$  are known, too, i.e.,  in the cases  $dim \leq
11$ or  $dim \in \{13,17,19,23\}$, the  classes of $Q_1($<dim>$)$ precede
those of $Q_2($<dim>$)$ and hence are numbered from 1 to $q_1($<dim>$)$.

`ImfNumberQClasses'  returns  the  number of $\Q$-classes    of groups of
dimension <dim>  which are available in the  library. If $dim \leq 11$ or
$dim      \in \{13,17,19,23\}$,  this  is     the  number $q_1($<dim>$) +
q_2($<dim>$)$ of  $\Q$-classes  of  i.m.f.~subgroups of   $GL_{dim}(\Z)$.
Otherwise, it is   just  the number  $q_1($<dim>$)$ of   $\Q$-classes  of
i.m.f.~subgroups of $GL_{dim}(\Q)$.    Valid  values of <dim>     are all
positive integers up to 31.

`ImfNumberZClasses' returns the  number of $\Z$-classes in  the <q>$^{\rm
th}$   $\Q$-class   of  i.m.f.~integral    matrix   groups  of  dimension
<dim>. Valid values of <dim> are all  positive integers up  to 11 and all
primes up to 23.

\>DisplayImfInvariants( <dim>, <q> ) F
\>DisplayImfInvariants( <dim>, <q>, <z> ) F

`DisplayImfInvariants'  displays the  following $\Z$-class invariants  of
the   groups in the  <z>$^{\rm   th}$  $\Z$-class  in the  <q>$^{\rm th}$
$\Q$-class of i.m.f.~integral matrix groups of dimension <dim>:

\beginlist%unordered
\item{--}
      its  $\Z$-class number  in the form  <dim>.<q>.<z>,  if <dim> is at
      most 11 or a prime at most 23, or its $\Q$-class number in the form
      <dim>.<q>, else,
\item{--}
      a message if the group is solvable,
\item{--}
      the size of the group,
\item{--}
      the isomorphism type of the group,
\item{--}
      the   elementary  divisors   of  the   associated  quadratic  form,
\item{--}
      the sizes  of the  orbits  of short vectors  (these  sizes  are the
      degrees of the  faithful permutation representations  which you may
      construct    using    the   functions   `IsomorphismPermGroup'   or
      `IsomorphismPermGroupImfGroup' below),
\item{--}
      the norm of the associated short vectors,
\item{--}
      only  in  case  that  the  group  is  not  an  i.m.f.~group  in
      $GL_n(\Q)$:  an  appropriate  message,  including the  $\Q$-class
      number    of   the    corresponding   rational    i.m.f.~class.
\endlist

If you specify the value 0 for any of the parameters  <dim>, <q>, or <z>,
the   command will loop over all   available  dimensions, $\Q$-classes of
given  dimension,     or  $\Z$-classes  within    the   given $\Q$-class,
respectively. Otherwise, the values of the arguments must be in range.  A
value <z>$ \neq  1$ must  not be specified  if  the $\Z$-classes are  not
known  for the given  dimension,  i.e., if $dim  >  11$ and $dim \not \in
\{13,17,19,23\}$. The  default value of <z> is~1.  This value of <z> will
be accepted even if the $\Z$-classes are not known. Then it specifies the
only  representative group  which  is  available for  the <q>$^{\rm  th}$
$\Q$-class. The greatest legal value of <dim> is 31.

\beginexample
gap> DisplayImfInvariants( 3, 1, 0 );
#I Z-class 3.1.1:  Solvable, size = 2^4*3
#I   isomorphism type = C2 wr S3 = C2 x S4 = W(B3)
#I   elementary divisors = 1^3
#I   orbit size = 6, minimal norm = 1
#I Z-class 3.1.2:  Solvable, size = 2^4*3
#I   isomorphism type = C2 wr S3 = C2 x S4 = C2 x W(A3)
#I   elementary divisors = 1*4^2
#I   orbit size = 8, minimal norm = 3
#I Z-class 3.1.3:  Solvable, size = 2^4*3
#I   isomorphism type = C2 wr S3 = C2 x S4 = C2 x W(A3)
#I   elementary divisors = 1^2*4
#I   orbit size = 12, minimal norm = 2
gap> DisplayImfInvariants( 8, 15, 1 );
#I Z-class 8.15.1:  Solvable, size = 2^5*3^4
#I   isomorphism type = C2 x (S3 wr S3)
#I   elementary divisors = 1*3^3*9^3*27
#I   orbit size = 54, minimal norm = 8
#I   not maximal finite in GL(8,Q), rational imf class is 8.5
gap> DisplayImfInvariants( 20, 23 );
#I Q-class 20.23:  Size = 2^5*3^2*5*11
#I   isomorphism type = (PSL(2,11) x D12).C2
#I   elementary divisors = 1^18*11^2
#I   orbit size = 3*660 + 2*1980 + 2640 + 3960, minimal norm = 4
\endexample

Note that the function `DisplayImfInvariants' uses a kind of shorthand to
display the elementary divisors.  E.~g., the expression `1*3^3*9^3*27' in
the   preceding     example   stands   for   the   elementary    divisors
$1,3,3,3,9,9,9,27$.  (See also  the next  example  which  shows  that the
function  `ImfInvariants' provides the elementary  divisors in form of an
ordinary {\GAP} list.)

In  the description of the isomorphism  types the following notations are
used:
\beginitems
$A$ `x' $B$ &
      denotes a direct product of a group $A$ by a group $B$,

$A$ `subd' $B$ &
      denotes a subdirect product of $A$ by $B$,

$A$ `Y' $B$ &
      denotes a central product of $A$ by $B$,

$A$ `wr' $B$ &
      denotes a wreath product of $A$ by $B$,

$A`:'B$ &
      denotes a split extension of $A$ by $B$,

$A`.'B$ &
      denotes just an extension of $A$ by $B$ (split or nonsplit).
\enditems

The groups involved are
\beginlist%unordered
\item{--} the cyclic groups $C_n$, dihedral groups $D_n$,  and generalized
      quaternion groups  $Q_n$ of order $n$,  denoted by `C'<n>,  `D'<n>,
      and `Q'<n>, respectively,
\item{--} the  alternating groups  $A_n$  and  symmetric groups  $S_n$  of
      degree $n$, denoted by `A'<n> and `S'<n>, respectively,
\item{--} the  linear  groups   $GL_n(q)$,   $PGL_n(q)$,   $SL_n(q)$,  and
      $PSL_n(q)$,     denoted    by     `GL'(<n>,<q>),    `PGL'(<n>,<q>),
      `SL'(<n>,<q>), and `PSL'(<n>,<q>), respectively,
\item{--}  the  unitary  groups  $SU_n(q)$  and  $PSU_n(q)$,   denoted  by
      `SU'(<n>,<q>) and `PSU'(<n>,<q>), respectively,
\item{--} the  symplectic groups  $Sp(n,q)$  and  $PSp(n,q)$,  denoted  by
      `Sp'(<n>,<q>) and `PSp'(<n>,<q>), respectively,
\item{--} the  orthogonal groups   $O_8^{\,+}(2)$   and   $PO_8^{\,+}(2)$,
      denoted by `O+'(8,2) and `PO+'(8,2), respectively,
\item{--} the   extraspecial    groups    $2_+^{\,1+8}$,    $3_+^{\,1+2}$,
      $3_+^{\,1+4}$,  and   $5_+^{\,1+2}$,   denoted   by  `2+\^{}(1+8)',
      `3+\^{}(1+2)', `3+\^{}(1+4)', and `5+\^{}(1+2)', respectively,
\item{--} the Chevalley group $G_2(3)$, denoted by `G2(3)',
\item{--} the twisted Chevalley group ${^3D}_4(2)$, denoted by `3D4(2)',
\item{--} the Suzuki group $Sz(8)$, denoted by `Sz(8)',
\item{--} the Weyl groups   $W(A_n)$,  $W(B_n)$,  $W(D_n)$,  $W(E_n)$, and
      $W(F_4)$,  denoted by  `W(A<n>)',  `W(B<n>)', `W(D<n>)', `W(E<n>)',
      and `W(F4)', respectively,
\item{--} the sporadic simple groups  $Co_1$, $Co_2$, $Co_3$, $HS$, $J_2$,
      $M_{12}$, $M_{22}$, $M_{23}$, $M_{24}$, and $Mc$, denoted by `Co1',
      `Co2', `Co3',  `HS', `J2',  `M12', `M22', `M23', `M24',  and  `Mc',
      respectively,
\item{--} a point stabilizer of index 11 in $M_{11}$, denoted by `M10'.
\endlist

As   mentioned      above,  the   data    assembled   by    the  function
`DisplayImfInvariants'  are ``cheap data'' in  the sense that they can be
provided by the library without loading any of its  large matrix files or
performing any matrix calculations. The following  function allows you to
get proper access to these cheap data instead of just displaying them.

\>ImfInvariants( <dim>, <q> ) F
\>ImfInvariants( <dim>, <q>, <z> ) F

`ImfInvariants'   returns   a  record  which  provides   some  $\Z$-class
invariants of the groups   in   the <z>$^{\rm   th}$ $\Z$-class  in   the
<q>$^{\rm th}$ $\Q$-class  of i.m.f.~integral matrix groups  of dimension
<dim>.  A value  <z>$ \neq 1$ must not  be specified if  the $\Z$-classes
are not known for the given dimension, i.e., if  $dim > 11$ and $dim \not
\in \{13,17,19,23\}$. The  default value of <z> is~1.   This value of <z>
will   be  accepted even if  the  $\Z$-classes   are  not known.  Then it
specifies the   only  representative group   which  is available  for the
<q>$^{\rm th}$ $\Q$-class.  The greatest legal value of <dim> is 31.

The resulting record contains six or seven components:

\beginitems
`size' &
      the size of any representative group <G>,

`isSolvable' &
      is `true' if <G> is solvable,

`isomorphismType' &
      a text string describing the isomorphism type of  <G>  (in the same
      notation as used by the function `DisplayImfInvariants' above),

`elementaryDivisors' &
      the elementary divisors of the associated Gram matrix  <F>  (in the
      same format as the result of the  function `ElementaryDivisorsMat',
      see~"ElementaryDivisorsMat"),

`minimalNorm' &
      the norm of the associated short vectors,

`sizesOrbitsShortVectors' &
      the sizes of the orbits of short vectors under <F>,

`maximalQClass' &
      the  $\Q$-class  number  of  an  i.m.f.~group  in  $GL_n(\Q)$  that
      contains <G> as a subgroup  (only in case that not <G> itself is an
      i.m.f.~subgroup of $GL_n(\Q)$).
\enditems

Note that four of these data, namely the group size, the solvability, the
isomorphism  type, and the   corresponding rational i.m.f.~class, are not
only $\Z$-class invariants, but also $\Q$-class invariants.

Note further that, though the isomorphism type is a $\Q$-class invariant,
you will sometimes  get different descriptions for different $\Z$-classes
of the same $\Q$-class (as, e.g., for the  classes 3.1.1 and 3.1.2 in the
last example above). The purpose  of  this behaviour  is to provide  some
more information about the underlying lattices.

\beginexample
gap> ImfInvariants( 8, 15, 1 );
rec( size := 2592, isSolvable := true, isomorphismType := "C2 x (S3 wr S3)", 
  elementaryDivisors := [ 1, 3, 3, 3, 9, 9, 9, 27 ], minimalNorm := 8, 
  sizesOrbitsShortVectors := [ 54 ], maximalQClass := 5 )
gap> ImfInvariants( 24, 1 ).size;
10409396852733332453861621760000
gap> ImfInvariants( 23, 5, 2 ).sizesOrbitsShortVectors;
[ 552, 53130 ]
gap> for i in [ 1 .. ImfNumberQClasses( 22 ) ] do
>    Print( ImfInvariants( 22, i ).isomorphismType, "\n" ); od;
C2 wr S22 = W(B22)
(C2 x PSU(6,2)).S3
(C2 x S3) wr S11 = (C2 x W(A2)) wr S11
(C2 x S12) wr C2 = (C2 x W(A11)) wr C2
C2 x S3 x S12 = C2 x W(A2) x W(A11)
(C2 x HS).C2
(C2 x Mc).C2
C2 x S23 = C2 x W(A22)
C2 x PSL(2,23)
C2 x PSL(2,23)
C2 x PGL(2,23)
C2 x PGL(2,23)
\endexample

\>ImfMatrixGroup( <dim>, <q> ) F
\>ImfMatrixGroup( <dim>, <q>, <z> ) F

`ImfMatrixGroup'  is the essential   extraction function of  this library
(note  that its name has  been changed from  `ImfMatGroup' in {\GAP}~3 to
`ImfMatrixGroup' in {\GAP}~4).   It returns  a representative group,  <G>
say, of the <z>$^{\rm th}$ $\Z$-class in the <q>$^{\rm th}$ $\Q$-class of
i.m.f.~integral  matrix groups of dimension <dim>.  A  value <z>$ \neq 1$
must  not be specified  if the $\Z$-classes are not   known for the given
dimension,  i.e., if $dim >  11$ and $dim  \not \in \{13,17,19,23\}$. The
default value  of <z> is~1.   This value of  <z> will be accepted even if
the $\Z$-classes are not known. Then it specifies the only representative
group which is available for the <q>$^{\rm  th}$ $\Q$-class. The greatest
legal value of <dim> is 31.

\beginexample
gap> G := ImfMatrixGroup( 5, 1, 3 );
ImfMatrixGroup(5,1,3)
gap> for m in GeneratorsOfGroup( G ) do PrintArray( m ); od;
[ [  -1,   0,   0,   0,   0 ],
  [   0,   1,   0,   0,   0 ],
  [   0,   0,   0,   1,   0 ],
  [  -1,  -1,  -1,  -1,   2 ],
  [  -1,   0,   0,   0,   1 ] ]
[ [  0,  1,  0,  0,  0 ],
  [  0,  0,  1,  0,  0 ],
  [  0,  0,  0,  1,  0 ],
  [  1,  0,  0,  0,  0 ],
  [  0,  0,  0,  0,  1 ] ]
\endexample

The   attributes `Size' and   `IsSolvable' will be   properly  set in the
resulting     matrix group <G>.  In    addition,   it has two  attributes
`IsImfMatrixGroup' and `ImfRecord'  where the first one is just a logical
flag set to  true and the  latter one is a  record.  Except for the group
size and the  solvability flag, this  record contains the same components
as the resulting record  of the function `ImfInvariants' described  above
(see~"ImfInvariants"),   namely the    components      `isomorphismType',
`elementaryDivisors', `minimalNorm', and `sizesOrbitsShortVectors'   and,
if <G> is not a rational i.m.f.~group, `maximalQClass'.  Moreover, it has
the two components

\beginitems
`form' &
      the associated Gram matrix <F>, and

`repsOrbitsShortVectors' &
      representatives of the orbits of short vectors under <F>.
\enditems

The  last one  of  these  components  will be  required  by the  function
`IsomorphismPermGroup' below.

Example:

\beginexample
gap> Size( G );
3840
gap> imf := ImfRecord( G );;
gap> imf.isomorphismType;
"C2 wr S5 = C2 x W(D5)"
gap> PrintArray( imf.form );
[ [  4,  0,  0,  0,  2 ],
  [  0,  4,  0,  0,  2 ],
  [  0,  0,  4,  0,  2 ],
  [  0,  0,  0,  4,  2 ],
  [  2,  2,  2,  2,  5 ] ]
gap> imf.elementaryDivisors;
[ 1, 4, 4, 4, 4 ]
gap> imf.minimalNorm;
4
\endexample

If you want to perform calculations in such a matrix group <G> you should
be aware of the  fact that the permutation  group routines of {\GAP}  are
much more efficient than the  matrix group routines.  Hence we  recommend
that  you  do your  computations, whenever  possible,   in the isomorphic
permutation  group which is  induced by the action of  <G>  on one of the
orbits of the associated short vectors. You may call one of the following
functions `IsomorphismPermGroup' or `IsomorphismPermGroupImfGroup' to get
an  isomorphism  to such a  permutation group  (note  that these {\GAP}~4
functions   have   replaced   the   {\GAP}~3  functions  `PermGroup'  and
`PermGroupImfGroup').

\>IsomorphismPermGroup( <G> )!{for Imf matrix groups} M

returns an isomorphism, $\varphi$ say,  from  the  given  i.m.f.~integral
matrix group <G> to a permutation group $<P> := \varphi(<G>)$ acting on a
minimal orbit, $S$ say, of short vectors of <G>  such  that  each  matrix
$<m> \in <G>$ is mapped to the permutation induced by its action on $S$.

Note that in case of  a large orbit the  construction of $\varphi$ may be
space and  time consuming. Fortunately,  there are only six  $\Q$-classes
in the library for which the  smallest orbit of  short vectors is of size
greater than 20000, the worst case being the orbit of size 196560 for the
Leech lattice ($dim = 24$, $q = 3$).

The inverse isomorphism $\varphi^{-1}$ from <P> to  <G> is constructed by
determining a $\Q$-base $B \subset S$ of  $\Q^{1 \times dim}$ in $S$ and,
in addition,  the associated base change matrix  $M$ which transforms $B$
into  the standard base  of  $\Z^{1 \times dim}$.    This allows a simple
computation of  the preimage $\varphi^{-1}(p)$  of any permutation $p \in
P$ as follows.  If, for $1 \leq i \leq dim$, $b_i$ is the position number
in $S$ of the $i^{\rm th}$ base vector in $B$, it suffices to look up the
vector whose position number in  $S$ is the image of  $b_i$ under $p$ and
to   multiply this vector  by    $M$ to get   the  $i^{\rm  th}$ row   of
$\varphi^{-1}(p)$.

You may use     the functions `Image'  and   `PreImage'  (see~"Image" and
"PreImage") to switch from <G> to <P> and back from <P> to <G>.

As an  example, let  us continue  the preceding example  and  compute the
solvable residuum of the group <G>.

\beginexample
gap> # Perform the computations in an isomorphic permutation group.
gap> phi := IsomorphismPermGroup( G );;
gap> P := Image( phi );
Group([ (1,7,6)(2,9)(4,5,10), (2,3,4,5)(6,9,8,7) ])
gap> D := DerivedSubgroup( P );
Group([ (1,2,10,9)(3,8)(4,5)(6,7), (1,3,10,8)(2,5)(4,7)(6,9),
  (1,2,8,7,5)(3,4,6,10,9) ])
gap> Size( D );
960
gap> IsPerfectGroup( D );
true
gap> # We have found the solvable residuum of P,
gap> # now move the results back to the matrix group G.
gap> R := PreImage( phi, D );
<matrix group of size 960 with 3 generators>
gap> for m in GeneratorsOfGroup( R ) do PrintArray( m ); od;
[ [  -1,  -1,  -1,  -1,   2 ],
  [   0,  -1,   0,   0,   0 ],
  [   0,   0,   0,   1,   0 ],
  [   0,   0,   1,   0,   0 ],
  [  -1,  -1,   0,   0,   1 ] ]
[ [   0,   0,   0,   1,   0 ],
  [  -1,  -1,  -1,  -1,   2 ],
  [   0,   0,  -1,   0,   0 ],
  [   1,   0,   0,   0,   0 ],
  [   0,  -1,  -1,   0,   1 ] ]
[ [   0,  -1,   0,   0,   0 ],
  [   0,   0,   1,   0,   0 ],
  [   0,   0,   0,  -1,   0 ],
  [   1,   1,   1,   1,  -2 ],
  [   0,   0,   1,   0,  -1 ] ]
\endexample

\>IsomorphismPermGroupImfGroup( <G>, <n> ) F

`IsomorphismPermGroupImfGroup'    returns an  isomorphism, $\varphi$ say,
from  the given i.m.f.~integral  matrix group <G>  to a permutation group
<P> acting on the $<n>^{\rm th}$ orbit, $S$ say,  of short vectors of <G>
such that each matrix <m> $\in$ <G> is  mapped to the permutation induced
by its action on $S$.

The only difference to the  above function `IsomorphismPermGroup' is that
you  can specify the orbit to  be used.  In fact, as  the orbits of short
vectors    are   sorted   by     increasing     sizes, the       function
`IsomorphismPermGroup( <G> )'  has  been  implemented  such  that  it  is
equivalent to `IsomorphismPermGroupImfGroup( <G>, 1 )'.

\beginexample
gap> ImfInvariants( 12, 9 ).sizesOrbitsShortVectors;
[ 120, 300 ]
gap> G := ImfMatrixGroup( 12, 9 );
ImfMatrixGroup(12,9)
gap> phi1 := IsomorphismPermGroupImfGroup( G, 1 );;
gap> P1 := Image( phi1 );
<permutation group of size 2400 with 2 generators>
gap> LargestMovedPoint( P1 );
120
gap> phi2 := IsomorphismPermGroupImfGroup( G, 2 );;
gap> P2 := Image( phi2 );
<permutation group of size 2400 with 2 generators>
gap> LargestMovedPoint( P2 );
300
\endexample


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