<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %A  grplib.xml                  GAP documentation          Heiko Theißen -->
<!-- %A                                                         Volkmar Felsch -->
<!-- %A                                                         Bettina Eick -->
<!-- %A                                                         Alexander Hulpke -->
<!-- %A                                                         Hans Ulrich Besche -->
<!-- %% -->
<!-- %% -->
<!-- %Y  (C) 1998 School Math and Comp. Sci., University of St Andrews, Scotland -->
<!-- %Y  Copyright (C) 2002 The GAP Group -->
<!-- %% -->
<Chapter Label="Group Libraries">
<Heading>Group Libraries</Heading>

When you start &GAP;, it  already knows several groups. Currently &GAP;
initially knows the following groups:
<List>
<Item>
 some basic groups, such  as cyclic groups or symmetric
    groups (see&nbsp;<Ref Sect="Basic Groups"/>),
</Item>
<Item>
 classical matrix groups (see&nbsp;<Ref Sect="Classical Groups"/>),
</Item>
<Item>
 a library of transitive permutation groups,
    provided by the <Package>TransGrp</Package> package
    (see&nbsp;<Ref BookName="transgrp" Sect="Transitive Permutation Groups"/>),
</Item>
<Item>
 a library of groups of small order,
    provided by the <Package>SmallGrp</Package> package
    (see&nbsp;<Ref BookName="smallgrp" Chap="The Small Groups Library"/>),
</Item>
<Item>
 a libary of finite perfect groups,
    (see&nbsp;<Ref Sect="Finite Perfect Groups"/>),
</Item>
<Item>
 a library of primitive permutations groups,
    provided by the <Package>PrimGrp</Package> package
    (see&nbsp;<Ref BookName="primgrp" Sect="Primitive Permutation Groups"/>),
</Item>
<Item>
  the irreducible solvable subgroups of <M>GL(n,q)</M> for
    <M>n>1</M>, <M>q</M> a prime power and <M>q^n &lt; 2^{24}</M>,
    provided by the <Package>IRREDSOL</Package> package
    (see <Ref BookName="irredsol" Sect="Overview"/>),
</Item>
<Item>
 the irreducible maximal finite integral matrix groups
    of dimension at most  31
    (see&nbsp;<Ref Sect="Irreducible Maximal Finite Integral Matrix Groups"/>),
</Item>
<Item>
 the crystallographic groups of dimension at most 4, provided by the
     <Package>CrystCat</Package> package
    (see <Ref BookName="crystcat" Chap="The Crystallographic Groups Catalog"/>).
</Item>
</List>
<P/>
There   is usually no   relation  between the   groups  in the  different
libraries and a group may occur in different libraries in different
incarnations.
<P/>
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.
<P/>
&GAP; might use data libraries that are available to speed up calculations,
for example in using a classification to determine that groups must be
isomorphic, based on agreement of properties; or to determine maximal
subgroups or subgroup maximality. This will be indicated by an info message
of level 2 in the info class <C>InfoPerformance</C>.

If the calculation is to be independent of such data library use, for
example if it is used to verify the data library, functions can be called
with the option <C>NoPrecomputedData</C>, to turn these features off. Doing
so might cause significantly longer calculations, or even failure of certain
calculations.

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Basic Groups">
<Heading>Basic Groups</Heading>

<#Include Label="[1]{basic}">
<#Include Label="TrivialGroup">
<#Include Label="CyclicGroup">
<#Include Label="AbelianGroup">
<#Include Label="ElementaryAbelianGroup">
<#Include Label="FreeAbelianGroup">
<#Include Label="DihedralGroup">
<#Include Label="IsDihedralGroup">
<#Include Label="DicyclicGroup">
<#Include Label="IsQuaternionGroup">
<#Include Label="ExtraspecialGroup">
<#Include Label="AlternatingGroup">
<#Include Label="SymmetricGroup">
<#Include Label="MathieuGroup">
<#Include Label="SuzukiGroup">
<#Include Label="ReeGroup">

<Subsection Label="Generator Names">
<Heading>Generator Names</Heading>
For groups created as finitely presented groups, including polycyclic groups,
the generators are labelled, by default, with a letter and a number.
It is possible to influence this naming with the option <C>generatorNames</C>,
see Section&nbsp;<Ref Sect="Function Call With Options"/>.
If this option holds a string, then the generators are named with this
string and sequential numbers starting with <C>1</C>.
If this option holds a list of sufficient length consisting of
nonempty strings, then the generator names are taken from this list, in order.
<P/>
<Example><![CDATA[
gap> GeneratorsOfGroup(AbelianGroup([5,7]));
[ f1, f2 ]
gap> GeneratorsOfGroup(AbelianGroup([5,7]:generatorNames:="a"));
[ a1, a2 ]
gap> GeneratorsOfGroup(AbelianGroup([5,7]:generatorNames:=["u","v","w"]));
[ u, v ]
gap> AsSSortedList(DihedralGroup(12:generatorNames:="a"));
[ <identity> of ..., a1, a2, a3, a1*a2, a1*a3, a2*a3, a3^2, a1*a2*a3,
  a1*a3^2, a2*a3^2, a1*a2*a3^2 ]
gap> AsSSortedList(DihedralGroup(12:generatorNames:=["a","b","c"]));
[ <identity> of ..., a, b, c, a*b, a*c, b*c, c^2, a*b*c, a*c^2, b*c^2,
  a*b*c^2 ]
]]></Example>
</Subsection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Classical Groups">
<Heading>Classical Groups</Heading>

<#Include Label="[1]{classic}">
<#Include Label="GeneralLinearGroup">
<#Include Label="SpecialLinearGroup">
<#Include Label="GeneralUnitaryGroup">
<#Include Label="SpecialUnitaryGroup">
<#Include Label="SymplecticGroup">
<#Include Label="GeneralOrthogonalGroup">
<#Include Label="SpecialOrthogonalGroup">
<#Include Label="Omega_orthogonal_groups">
<#Include Label="GeneralSemilinearGroup">
<#Include Label="SpecialSemilinearGroup">
<#Include Label="ProjectiveGeneralLinearGroup">
<#Include Label="ProjectiveSpecialLinearGroup">
<#Include Label="ProjectiveGeneralUnitaryGroup">
<#Include Label="ProjectiveSpecialUnitaryGroup">
<#Include Label="ProjectiveSymplecticGroup">
<#Include Label="ProjectiveGeneralOrthogonalGroup">
<#Include Label="ProjectiveSpecialOrthogonalGroup">
<#Include Label="ProjectiveOmega">
<#Include Label="ProjectiveGeneralSemilinearGroup">
<#Include Label="ProjectiveSpecialSemilinearGroup">


</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Conjugacy Classes in Classical Groups">
<Heading>Conjugacy Classes in Classical Groups</Heading>

<Index Key="ConjugacyClasses" Subkey="for linear groups">
<C>ConjugacyClasses</C></Index>
For  general  and   special  linear  groups
(see&nbsp;<Ref Func="GeneralLinearGroup" Label="for dimension and a ring"/>
and&nbsp;<Ref Func="SpecialLinearGroup" Label="for dimension and a ring"/>)
&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.
<P/>
<Example><![CDATA[
gap> g := SL(4,9);
SL(4,9)
gap> NrConjugacyClasses(g);
861
gap> cl := ConjugacyClasses(g);;
gap> Length(cl);
861
]]></Example>
<P/>
<#Include Label="NrConjugacyClassesGL">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Constructors for Basic Groups">
<Heading>Constructors for Basic Groups</Heading>

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 <C>"Cons"</C>,
so for example <Ref Func="CyclicGroup"/> calls the constructor
<P/>
<C>CyclicGroupCons( <A>cat</A>, <A>n</A> )</C>
<P/>
The first argument <A>cat</A> 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&nbsp;<Ref Func="InstallMethod"/>
for the meaning of the arguments.
<P/>
<Log><![CDATA[
InstallMethod( CyclicGroupCons,
    "regular perm group",
    true,
    [ IsPermGroup and IsRegularProp and IsFinite, IsInt and IsPosRat ], 0,
    function( filter, n )

    ...

    end );
]]></Log>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Selection Functions">
<Heading>Selection Functions</Heading>

<Index Key="AllPrimitiveGroups"><C>AllPrimitiveGroups</C></Index>
<Index Key="AllTransitiveGroups"><C>AllTransitiveGroups</C></Index>
<Index Key="AllLibraryGroups"><C>All<A>Library</A>Groups</C></Index>
<C>All<A>Library</A>Groups( <A>fun1</A>, <A>val1</A>, ... )</C>
<P/>
For a number  of  the  group  libraries  two  <E>selection  functions</E>  are
provided. Each <C>All<A>Library</A>Groups</C> selection  function  permits  one  to
select <E>all</E> groups from the library <A>Library</A> that have a given  set  of
properties.
<!-- %The name of the selection  functions always begins  with <C>All</C> and always -->
<!-- %ends with <C>Groups</C>. In between is a  name that hints at the nature of the -->
<!-- %group library.  -->
Currently, the library selection functions provided, of  this  type,  are
<Ref BookName="smallgrp" Func="AllSmallGroups"/>,
<Ref BookName="primgrp" Func="AllIrreducibleSolvableGroups"/>,
<Ref BookName="transgrp" Func="AllTransitiveGroups"/>,
and <Ref BookName="primgrp" Func="AllPrimitiveGroups"/>.
Corresponding to  each  of  these  there  is  a
<C>One<A>Library</A>Group</C> function (see below) which  returns  at
most one group.
<P/>
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
<Ref BookName="smallgrp" Func="AllSmallGroups"/> the first such function must be
<Ref Attr="Size"/>, and, unlike  the
other library selection functions,  it  supports  an  alternative  syntax
where <Ref Attr="Size"/> is omitted
(see&nbsp;<Ref BookName="smallgrp" Func="AllSmallGroups"/>).
Also, see <Ref BookName="primgrp" Func="AllIrreducibleSolvableGroups"/>,
for details pertaining to this function.
<P/>
For an example, let us consider the selection function for the library of
transitive groups
(also see&nbsp;<Ref BookName="transgrp" Sect="Transitive Permutation Groups"/>).
The command
<P/>
<Log><![CDATA[
gap> AllTransitiveGroups(NrMovedPoints,[10..15],
>                        Size,         [1..100],
>                        IsAbelian,    false    );
]]></Log>
<P/>
returns a list of all transitive groups with degree between 10 and 15 and
size less than 100 that are not abelian.
<P/>
Thus <C>AllTransitiveGroups</C> behaves as if it was implemented by a
function similar to the one defined below,
where <C>TransitiveGroupsList</C> is a list of all transitive groups.
(Note that in the definition below we assume for simplicity that
<C>AllTransitiveGroups</C> 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.)
<P/>
<Log><![CDATA[
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;
]]></Log>
<P/>
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.
<P/>
<Index Key="OnePrimitiveGroup"><C>OnePrimitiveGroup</C></Index>
<Index Key="OneTransitiveGroup"><C>OneTransitiveGroup</C></Index>
<Index Key="OneLibraryGroup"><C>One<A>Library</A>Group</C></Index>
<C>One<A>Library</A>Group( <A>fun1</A>, <A>val1</A>, ... )</C>
<P/>
For each <C>All<A>Library</A>Groups</C> function (see above) there is
a corresponding function <C>One<A>Library</A>Group</C> on exactly the same
arguments, i.e., there are
<Ref BookName="smallgrp" Func="OneSmallGroup"/>,
<Ref BookName="primgrp" Func="OneIrreducibleSolvableGroup"/>,
<Ref BookName="transgrp" Func="OneTransitiveGroup"/>,
and <Ref BookName="primgrp" Func="OnePrimitiveGroup"/>.
Each function simply returns <E>one</E> group in
the library that has the prescribed properties,
instead of <E>all</E> such groups.
It returns <K>fail</K> if no such group exists in the library.

</Section>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Finite Perfect Groups">
<Heading>Finite Perfect Groups</Heading>

<Index>perfect groups</Index>
The &GAP; library of finite  perfect groups provides, up to isomorphism, a
list of all perfect groups whose sizes are less than  <M>2\cdot 10^6</M>.
The groups of orders up to <M>10^6</M> have been enumerated by
Derek&nbsp;F. Holt and Wilhelm Plesken and
published in their  book    <Q>Perfect Groups</Q> <Cite Key="HP89"/>.
For orders <M>n = 86016</M>,  368640,  or  737280 this work only counted the
groups (but did not explicitly list them), the groups of orders
<M>n = 61440</M>, 122880, 172032, 245760, 344064, 491520,
688128, or 983040 were omitted.
<P/>
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 of these has been brought into &GAP; format by Volkmar Felsch.
<P/>
Several additional groups omitted from the book <Q>Perfect Groups</Q> have also
been included. Two groups -- one of order 450000 with a factor group of
type <M>A_6</M> and the one of order 962280 -- were found by Jack Schmidt in
2005. Two groups of order 243000 and one each of orders 729000, 871200, 878460
were found in 2020 by Alexander Hulpke.
<P/>
The perfect groups of size less than <M>2\cdot 10^6</M> which had not been
classified in the work of Holt and Plesken have been enumerated by Alexander
Hulpke. They are stored directly and provide less construction information
in their names.
<P/>
<P/>
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.

<#Include Label="SizesPerfectGroups">
<#Include Label="PerfectGroup">
<#Include Label="PerfectIdentification">
<#Include Label="NumberPerfectGroups">
<#Include Label="SizeNumbersPerfectGroups">
<#Include Label="DisplayInformationPerfectGroups">

<Subsection Label="More about the Perfect Groups Library">
<Heading>More about the Perfect Groups Library</Heading>

For any library  group  <M>G</M>, the library    files do not  only provide  a
presentation, but, in  addition, a list  of  one or more subgroups  <M>S_1,
\ldots,  S_r</M>  of   <M>G</M> such   that   there is  a   faithful  permutation
representation of <M>G</M> of degree <M>\sum_{{i = 1}}^r [G:S_i]</M>
on the set <M>\{ S_i g \mid 1 \leq i \leq r, g \in G \}</M>
of the cosets of the <M>S_i</M>.
This allows one to construct the groups as permutation groups.
The function <Ref Func="DisplayInformationPerfectGroups"
Label="for group order (and index)"/> displays only the available degree.
The message
<Log><![CDATA[
orbit size = 8
]]></Log>
<P/>
in the above example means that the available permutation representation
is transitive and of degree 8, whereas the message
<Log><![CDATA[
orbit sizes = 5 + 16
]]></Log>
means that a nontransitive  permutation representation is available which
acts on two orbits of size 5 and 16 respectively.
<P/>
The  notation used in  the <Q>description</Q>  of  a  group is explained  in
section&nbsp;5.1.2 of <Cite Key="HP89"/>.
We quote the respective page from there:
<P/>
Within a class <M>Q\,\#\,p</M>, an isomorphism type of groups will be  denoted
by an ordered pair of integers <M>(r,n)</M>, where <M>r \geq 0</M>  and  <M>n  >  0</M>.
More precisely, the isomorphism types in <M>Q \# p</M> of order <M>p^r |Q|</M> will
be denoted by <M>(r,1), (r,2), (r,3), \ldots\,</M>. Thus <M>Q</M> will  always  get
the size number <M>(0,1)</M>.
<P/>
In addition to the symbol <M>(r,n)</M>, the groups in <M>Q\,\#\,p</M> 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
<M>F_pQ</M>-modules <M>M</M> with <M>|Q|.|M| \leq 10^6</M>, where <M>F_p</M> is the field  of
order <M>p</M>, are assigned symbols.
These will either be simply <M>p^x</M>, where <M>x</M> 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<M>p^x</M>,
<M>p^{{x'}}</M>, etc.
The  one-dimensional  module
with trivial <M>Q</M>-action will therefore be denoted by <M>p^1</M>. These symbols
will be listed under the description of  <M>Q</M>.  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 <M>Q</M>  itself.
(This convention is the  most  convenient  in  our  context,  but  it  is
different from that adopted in the ATLAS <Cite Key="CCN85"/>, for example, where
composition factors are listed in the  reverse  order.  For  example,  we
denote a group isomorphic to <M>SL(2,5)</M> by <M>A_5 2^1</M> rather than <M>2.A_5</M>.)
<P/>
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.
<P/>
<List>
<Mark><M>\times</M></Mark>
<Item>
  between  two  factors   denotes   a  direct  product  of
      <M>F_pQ</M>-modules or groups.
</Item>
<Mark>C</Mark>
<Item>
 (for <Q>commutator</Q>) between two factors  means  that the second
      lies in the commutator subgroup of the first.  Similarly, a segment
      of the form  <M>(f_1 \! \times \! f_2) C f_3</M>  would mean  that
      the factors <M>f_1</M> and <M>f_2</M>  commute modulo <M>f_3</M> and <M>f_3</M> lies in
      <M>[f_1,f_2]</M>.
</Item>
<Mark>A</Mark>
<Item>
 (for <Q>abelian</Q>) between two factors  indicates that the second
      is  in the  <M>p</M>th  power  (but not the commutator subgroup)  of the
      first.   <Q>A</Q>   may  also   follow  the  factors,   if  bracketed.
</Item>
<Mark>E</Mark>
<Item>
 (for <Q>elementary abelian</Q>) between two factors  indicates that
      together   they  generate  an  elementary  abelian  group   (modulo
      subsequent factors), but that the resulting <M>F_p Q</M>-module extension
      does not split.
</Item>
<Mark>N</Mark>
<Item>
  (for <Q>nonsplit</Q>) before  a  factor  indicates  that  <M>Q</M>  (or
      possibly its covering group)  splits down as far at this factor but
      not over the factor itself.  So  <Q><M>Q f_1 N f_2</M></Q> means that
      the normal subgroup  <M>f_1 f_2</M>  of the group  has no complement but,
      modulo <M>f_2</M>, <M>f_1</M>, does have a complement.
</Item>
</List>
<P/>
Brackets have their obvious meaning. Summarizing, we have:
<P/>
<List>
<Mark><M>\times</M></Mark>
<Item>
 = direct product;
</Item>
<Mark>C</Mark>
<Item>
 = commutator subgroup;
</Item>
<Mark>A</Mark>
<Item>
 = abelian;
</Item>
<Mark>E</Mark>
<Item>
 = elementary abelian; and
</Item>
<Mark>N</Mark>
<Item>
 = nonsplit.
</Item>
</List>
<P/>
Here are some examples.
<P/>
<List>
<Mark>(i)</Mark>
<Item>
  <M>A_5 (2^4 E 2^1 E 2^4) A</M>  means  that  the
      pairs  <M>2^4 E 2^1</M>  and <M>2^1 E 2^4</M> are both elementary
      abelian of exponent 4.
</Item>
<Mark>(ii)</Mark>
<Item>
   <M>A_5 (2^4 E 2^1 A) C 2^1</M> means that
   <M>O_2(G)</M> is of symplectic type <M>2^{{1+5}}</M>,
   with Frattini factor group of type <M>2^4 E 2^1</M>.
   The <Q>A</Q> after the <M>2^1</M> indicates that <M>G</M> has a central
   cyclic subgroup <M>2^1 A 2^1</M> of order 4.
</Item>
<Mark>(iii)</Mark>
<Item>
   <M>L_3(2) ((2^1 E) \! \times \! ( N 2^3 E 2^{{3'}} A) C) 2^{{3'}}</M>
      means that the <M>2^{{3'}}</M>
      factor at the bottom lies in the commutator subgroup
      of the pair <M>2^3 E 2^{{3'}}</M> in the middle, but the lower
      pair <M>2^{{3'}} A 2^{{3'}}</M>  is abelian of exponent 4.
      There  is  also  a submodule  <M>2^1 E 2^{{3'}}</M>,  and  the
      covering group  <M>L_3(2) 2^1</M>  of  <M>L_3(2)</M>  does not split over the
      <M>2^3</M>  factor.  (Since <M>G</M> is perfect,  it goes without saying that
      the extension <M>L_3(2) 2^1</M> cannot split itself.)
</Item>
</List>
<P/>
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.
<P/>
If such a group description has been given in the book for <M>G</M>
(and, in fact, this is the case for most of the library groups),
it is displayed by <Ref Func="DisplayInformationPerfectGroups"
Label="for group order (and index)"/>.
Otherwise the function provides a less explicit description of the
(in these cases unique) Holt-Plesken class to which <M>G</M> belongs,
together with a serial number if this is necessary to make it unique.

</Subsection>
</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Irreducible Maximal Finite Integral Matrix Groups">
<Heading>Irreducible Maximal Finite Integral Matrix Groups</Heading>

A   library of irreducible   maximal finite   integral  matrix groups  is
provided with &GAP;. It  contains <M>&QQ;</M>-class representatives for  all of
these groups of dimension at  most 31, and <M>&ZZ;</M>-class representatives for
those of dimension at most 11 or of dimension 13, 17, 19, or 23.
<P/>
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ü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 Key="PP77"/>, <Cite Key="PP80"/>). The  <M>&ZZ;</M>-class  representatives of the
groups  of  dimension  10 have  been  determined and    computed by Bernd
Souvignier (<Cite Key="Sou94"/>),  and those of  dimensions 11, 13,  and 17 have
been  recomputed for this library from  the circulant Gram matrices given
in  <Cite Key="Ple85"/>, using the  stand-alone  programs for the computation of
short vectors and Bravais groups which have  been developed in  Plesken's
institute. The <M>&ZZ;</M>-class representatives of  the groups of dimensions 19
and  23 had already been  determined in  <Cite Key="Ple85"/>.  Gabriele Nebe has
recomputed them  for us. Her  main contribution to this library, however,
is that she has determined and computed the <M>&QQ;</M>-class representatives of
the groups  of non-prime dimensions  between 12 and  24 and the groups of
dimensions  25  to  31   (see   <Cite Key="PN95"/>,  <Cite Key="NP95"/>,  <Cite Key="Neb95"/>,
<Cite Key="Neb96"/>).
<P/>
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;.
<P/>
In the preceding  acknowledgement, we used  some notations that will also
be needed in the sequel. We first define these.
<P/>
Any  integral matrix   group  <M>G</M>  of  dimension   <M>n</M> is a  subgroup  of
<M>GL_n(&ZZ;)</M> as  well  as of  <M>GL_n(&QQ;)</M>  and hence lies in  some conjugacy
class of integral  matrix groups   under  <M>GL_n(&ZZ;)</M>  and also in    some
conjugacy class of rational matrix  groups under <M>GL_n(&QQ;)</M>. As usual, we
call  these  classes    the  <M>&ZZ;</M>-class   and the   <M>&QQ;</M>-class   of  <M>G</M>,
respectively.  Note that any conjugacy  class of subgroups of  <M>GL_n(&QQ;)</M>
contains at least one <M>&ZZ;</M>-class of subgroups of <M>GL_n(&ZZ;)</M> and hence can
be considered as the <M>&QQ;</M>-class of some integral matrix group.
<P/>
In  the context of  this library we are  only concerned with <M>&ZZ;</M>-classes
and <M>&QQ;</M>-classes of subgroups   of <M>GL_n(&ZZ;)</M> which are irreducible   and
maximal   finite in <M>GL_n(&ZZ;)</M> (we   will call them <E>i.m.f.</E>&nbsp;subgroups of
<M>GL_n(&ZZ;)</M>).  We can distinguish two types of these groups:
<P/>
First, there are  those  i.m.f.&nbsp;subgroups  of <M>GL_n(&ZZ;)</M> which   are also
maximal  finite subgroups of <M>GL_n(&QQ;)</M>.  Let  us denote the set of their
<M>&QQ;</M>-classes by <M>Q_1(n)</M>. It is clear from the above remark that <M>Q_1(n)</M>
just consists of the <M>&QQ;</M>-classes of i.m.f.&nbsp;subgroups of <M>GL_n(&QQ;)</M>.
<P/>
Secondly, there is the set <M>Q_2(n)</M> of the  <M>&QQ;</M>-classes of the remaining
i.m.f.&nbsp;subgroups of <M>GL_n(&ZZ;)</M>, i.e.,  of   those which are  not  maximal
finite subgroups of <M>GL_n(&QQ;)</M>. For any such group <M>G</M>, there is at
least one class <M>C \in Q_1(n)</M> such that <M>G</M> is conjugate under <M>&QQ;</M> to a
proper subgroup of some   group <M>H \in C</M>.   In  fact, the class <M>C</M>   is
uniquely determined for any group   <M>G</M> occurring in the library  (though
there seems to be no  reason to assume that  this property should hold in
general).  Hence   we may   call   <M>C</M>  the <E>rational   i.m.f.&nbsp;class</E>  of
<M>G</M>. Finally, we  will  denote the   number of  classes  in  <M>Q_1(n)</M> and
<M>Q_2(n)</M> by <M>q_1(n)</M> and <M>q_2(n)</M>, respectively.
<P/>
As an example, let us consider the case <M>n = 4</M>. There are 6 <M>&ZZ;</M>-classes
of i.m.f.&nbsp;subgroups  of <M>GL_4(&ZZ;)</M>   with representative subgroups  <M>G_1,
\ldots,  G_6</M> of isomorphism types  <M>G_1 \cong W(F_4)</M>, <M>G_2 \cong D_{12}
\wr C_2</M>, <M>G_3 \cong  G_4 \cong C_2 \times  S_5</M>, <M>G_5 \cong W(B_4)</M>, and
<M>G_6  \cong (D_{12}  </M><C>Y</C><M>  D_{12})   \!:\! C_2</M>.  The    corresponding
<M>&QQ;</M>-classes, which we denote <M>R_1, \ldots, R_6</M>, are pairwise different except that
<M>R_3</M> coincides  with <M>R_4</M>.   The  groups <M>G_1</M>,  <M>G_2</M>, and  <M>G_3</M>  are
i.m.f.&nbsp;subgroups of <M>GL_4(&QQ;)</M>, but <M>G_5</M>  and <M>G_6</M> are not because they
are  conjugate under <M>GL_4(&QQ;)</M> to proper  subgroups  of <M>G_1</M> and <M>G_2</M>,
respectively.  So we  have <M>Q_1(4) = \{ R_1,  R_2, R_3 \}</M>,  <M>Q_2(4) = \{
R_5, R_6 \}</M>, <M>q_1(4) = 3</M>, and <M>q_2(4) = 2</M>.
<P/>
The <M>q_1(n)</M> <M>&QQ;</M>-classes   of i.m.f.&nbsp;subgroups of  <M>GL_n(&QQ;)</M>  have been
determined  for each dimension  <M>n \leq 31</M>.   The current &GAP; library
provides integral representative groups for all these classes.  Moreover,
all <M>&ZZ;</M>-classes of i.m.f.&nbsp;subgroups of <M>GL_n(&ZZ;)</M>  are known for <M>n \leq
11</M> and  for <M>n \in \{13,17,19,23\}</M>. For   these dimensions, the library
offers integral  representative  groups for all <M>&QQ;</M>-classes  in <M>Q_1(n)</M>
and <M>Q_2(n)</M> as  well as  for   all <M>&ZZ;</M>-classes  of i.m.f.&nbsp;subgroups  of
<M>GL_n(&ZZ;)</M>.
<P/>
Any group <M>G</M> of dimension <M>n</M> given in the library is represented
as the automorphism group
<M>G = Aut(F,L) = \{ g \in GL_n(&ZZ;) \mid Lg = L, g F g^{tr} = F \}</M>
of a positive definite symmetric <M>n \times n</M> matrix
<M>F \in &ZZ;^{{n \times n}}</M> on an <M>n</M>-dimensional lattice
<M>L \cong &ZZ;^{{1 \times n}}</M>
(for details see e.g. <Cite Key="PN95"/>).
&GAP; provides for <M>G</M> a list of matrix generators and the
<E>Gram matrix</E> <M>F</M>.
<P/>
The positive definite quadratic form defined by <M>F</M> defines a
<E>norm</E> <M>v F v^{tr}</M> for each vector <M>v \in L</M>,
and there is only a finite set of vectors of minimal norm.
These vectors are often simply called the <E>short vectors</E>.
Their set splits into  orbits under <M>G</M>, and <M>G</M> 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.
<P/>
Like most of the  other &GAP; libraries,  the library of i.m.f.&nbsp;integral
matrix   groups   supplies an   extraction   function,  <C>ImfMatrixGroup</C>.
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,
<Ref Func="ImfInvariants"/> and <Ref Func="DisplayImfInvariants"/>,
which provide some
<M>&ZZ;</M>-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.
<P/>
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  <E>irreducible maximal
finite integral  matrix groups</E> would  have to include  this term in full
length and hence would grow extremely long.  Therefore we have decided to
use the abbreviation <C>Imf</C> instead in order to restrict the names to some
reasonable length.
<P/>
The  first  three  functions can   be  used to formulate  loops  over the
classes.
<P/>
<ManSection>
<Func Name="ImfNumberQQClasses" Arg='dim'/>
<Func Name="ImfNumberQClasses" Arg='dim'/>
<Func Name="ImfNumberZClasses" Arg='dim, q'/>

<Description>
<C>ImfNumberQQClasses</C> returns the number <M>q_1(</M><A>dim</A><M>)</M> of <M>&QQ;</M>-classes of
i.m.f.&nbsp;rational matrix groups of dimension  <A>dim</A>. Valid values of  <A>dim</A>
are all positive integers up to 31.
<P/>
Note: In order  to enable you to loop  just over the classes belonging to
<M>Q_1(</M><A>dim</A><M>)</M>, we have  arranged  the list of <M>&QQ;</M>-classes  of dimension
<A>dim</A>  for any dimension  <A>dim</A>  in the  library such that,  whenever the
classes of <M>Q_2(</M><A>dim</A><M>)</M>  are known, too, i.e.,  in the cases  <M>dim \leq
11</M> or  <M>dim \in \{13,17,19,23\}</M>, the  classes of <M>Q_1(</M><A>dim</A><M>)</M> precede
those of <M>Q_2(</M><A>dim</A><M>)</M> and hence are numbered from 1 to <M>q_1(</M><A>dim</A><M>)</M>.
<P/>
<C>ImfNumberQClasses</C>  returns  the  number of <M>&QQ;</M>-classes    of groups of
dimension <A>dim</A>  which are available in the  library. If <M>dim \leq 11</M> or
<M>dim      \in \{13,17,19,23\}</M>,  this  is     the  number <M>q_1(</M><A>dim</A><M>) +
q_2(</M><A>dim</A><M>)</M> of  <M>&QQ;</M>-classes  of  i.m.f.&nbsp;subgroups of   <M>GL_{dim}(&ZZ;)</M>.
Otherwise, it is   just  the number  <M>q_1(</M><A>dim</A><M>)</M> of   <M>&QQ;</M>-classes  of
i.m.f.&nbsp;subgroups of <M>GL_{dim}(&QQ;)</M>.    Valid  values of <A>dim</A>     are all
positive integers up to 31.
<P/>
<Ref Func="ImfNumberZClasses"/> returns the number of <M>&ZZ;</M>-classes
in the <A>q</A>-th <M>&QQ;</M>-class of i.m.f.&nbsp;integral matrix groups
of dimension <A>dim</A>.
Valid values of <A>dim</A> are all  positive integers up  to 11 and all
primes up to 23.
</Description>
</ManSection>
<P/>
<ManSection>
<Func Name="DisplayImfInvariants" Arg='dim, q[, z]'/>

<Description>
<Ref Func="DisplayImfInvariants"/> displays the following
<M>&ZZ;</M>-class invariants of the groups in the
<A>z</A>-th <M>&ZZ;</M>-class in the <A>q</A>-th <M>&QQ;</M>-class of
i.m.f.&nbsp;integral matrix groups of dimension <A>dim</A>:
<P/>
<List>
<Item>
      its  <M>&ZZ;</M>-class number  in the form  <A>dim</A>.<A>q</A>.<A>z</A>,  if <A>dim</A> is at
      most 11 or a prime at most 23, or its <M>&QQ;</M>-class number in the form
      <A>dim</A>.<A>q</A>, else,
</Item>
<Item>
      a message if the group is solvable,
</Item>
<Item>
      the size of the group,
</Item>
<Item>
      the isomorphism type of the group,
</Item>
<Item>
      the   elementary  divisors   of  the   associated  quadratic  form,
</Item>
<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
      <Ref Meth="IsomorphismPermGroup" Label="for Imf matrix groups"/> or
      <Ref Func="IsomorphismPermGroupImfGroup"/> below),
</Item>
<Item>
      the norm of the associated short vectors,
</Item>
<Item>
      only  in  case  that  the  group  is  not  an  i.m.f.&nbsp;group  in
      <M>GL_n(&QQ;)</M>:  an  appropriate  message,  including the  <M>&QQ;</M>-class
      number    of   the    corresponding   rational    i.m.f.&nbsp;class.
</Item>
</List>
<P/>
If you specify the value 0 for any of the parameters <A>dim</A>, <A>q</A>,
or <A>z</A>,
the command will loop over all available dimensions, <M>&QQ;</M>-classes of
given dimension, or <M>&ZZ;</M>-classes within the given <M>&QQ;</M>-class,
respectively. Otherwise, the values of the arguments must be in range.  A
value <A>z</A> <M>\neq 1</M> must not be specified if the <M>&ZZ;</M>-classes
are not known for the given dimension, i.e., if <A>dim</A> <M>> 11</M> and
<A>dim</A> <M>\not \in \{ 13, 17, 19, 23 \}</M>.
The default value of <A>z</A> is&nbsp;1.  This value of <A>z</A> will
be accepted even if the <M>&ZZ;</M>-classes are not known.
Then it specifies the only representative group which is available for the
<A>q</A>-th <M>&QQ;</M>-class.
The greatest legal value of <A>dim</A> is 31.
<P/>
<Example><![CDATA[
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
]]></Example>
<P/>
Note that the function <Ref Func="DisplayImfInvariants"/> uses a kind of
shorthand to display the elementary divisors.
E.&nbsp;g., the expression <C>1*3^3*9^3*27</C> in
the   preceding     example   stands   for   the   elementary    divisors
<M>1,3,3,3,9,9,9,27</M>.  (See also  the next  example  which  shows  that the
function <Ref Func="ImfInvariants"/> provides the elementary  divisors in form of an
ordinary &GAP; list.)
<P/>
In  the description of the isomorphism  types the following notations are
used:
<List>
<Mark><M>A</M> <C>x</C> <M>B</M> </Mark>
<Item>
      denotes a direct product of a group <M>A</M> by a group <M>B</M>,
</Item>
<Mark><M>A</M> <C>subd</C> <M>B</M> </Mark>
<Item>
      denotes a subdirect product of <M>A</M> by <M>B</M>,
</Item>
<Mark><M>A</M> <C>Y</C> <M>B</M> </Mark>
<Item>
      denotes a central product of <M>A</M> by <M>B</M>,
</Item>
<Mark><M>A</M> <C>wr</C> <M>B</M> </Mark>
<Item>
      denotes a wreath product of <M>A</M> by <M>B</M>,
</Item>
<Mark><M>A</M><C>:</C><M>B</M> </Mark>
<Item>
      denotes a split extension of <M>A</M> by <M>B</M>,
</Item>
<Mark><M>A</M><C>.</C><M>B</M> </Mark>
<Item>
      denotes just an extension of <M>A</M> by <M>B</M> (split or nonsplit).
</Item>
</List>
<P/>
The groups involved are
<List>
<Item>
 the cyclic groups <M>C_n</M>, dihedral groups <M>D_n</M>,  and generalized
      quaternion groups  <M>Q_n</M> of order <M>n</M>,  denoted by <C>C</C><A>n</A>,  <C>D</C><A>n</A>,
      and <C>Q</C><A>n</A>, respectively,
</Item>
<Item>
 the  alternating groups  <M>A_n</M>  and  symmetric groups  <M>S_n</M>  of
      degree <M>n</M>, denoted by <C>A</C><A>n</A> and <C>S</C><A>n</A>, respectively,
</Item>
<Item>
 the  linear  groups   <M>GL_n(q)</M>,   <M>PGL_n(q)</M>,   <M>SL_n(q)</M>,  and
      <M>PSL_n(q)</M>,     denoted    by     <C>GL</C>(<A>n</A>,<A>q</A>),    <C>PGL</C>(<A>n</A>,<A>q</A>),
      <C>SL</C>(<A>n</A>,<A>q</A>), and <C>PSL</C>(<A>n</A>,<A>q</A>), respectively,
</Item>
<Item>
  the  unitary  groups  <M>SU_n(q)</M>  and  <M>PSU_n(q)</M>,   denoted  by
      <C>SU</C>(<A>n</A>,<A>q</A>) and <C>PSU</C>(<A>n</A>,<A>q</A>), respectively,
</Item>
<Item>
 the  symplectic groups  <M>Sp(n,q)</M>  and  <M>PSp(n,q)</M>,  denoted  by
      <C>Sp</C>(<A>n</A>,<A>q</A>) and <C>PSp</C>(<A>n</A>,<A>q</A>), respectively,
</Item>
<Item>
 the  orthogonal groups   <M>O_8^+(2)</M>   and   <M>PO_8^+(2)</M>,
      denoted by <C>O+</C>(8,2) and <C>PO+</C>(8,2), respectively,
</Item>
<Item>
   the extraspecial groups <M>2_+^{{1+8}}</M>, <M>3_+^{{1+2}}</M>,
   <M>3_+^{{1+4}}</M>, and <M>5_+^{{1+2}}</M>, denoted by <C>2+^(1+8)</C>,
   <C>3+^(1+2)</C>, <C>3+^(1+4)</C>, and <C>5+^(1+2)</C>, respectively,
</Item>
<Item>
 the Chevalley group <M>G_2(3)</M>, denoted by <C>G2(3)</C>,
</Item>
<Item>
 the twisted Chevalley group <M>{^3}D_4(2)</M>, denoted by <C>3D4(2)</C>,
</Item>
<Item>
 the Suzuki group <M>Sz(8)</M>, denoted by <C>Sz(8)</C>,
</Item>
<Item>
 the Weyl groups   <M>W(A_n)</M>,  <M>W(B_n)</M>,  <M>W(D_n)</M>,  <M>W(E_n)</M>, and
      <M>W(F_4)</M>,  denoted by  <C>W(A<A>n</A>)</C>,  <C>W(B<A>n</A>)</C>, <C>W(D<A>n</A>)</C>, <C>W(E<A>n</A>)</C>,
      and <C>W(F4)</C>, respectively,
</Item>
<Item>
 the sporadic simple groups  <M>Co_1</M>, <M>Co_2</M>, <M>Co_3</M>, <M>HS</M>, <M>J_2</M>,
      <M>M_{12}</M>, <M>M_{22}</M>, <M>M_{23}</M>, <M>M_{24}</M>, and <M>Mc</M>, denoted by <C>Co1</C>,
      <C>Co2</C>, <C>Co3</C>,  <C>HS</C>, <C>J2</C>,  <C>M12</C>, <C>M22</C>, <C>M23</C>, <C>M24</C>,  and  <C>Mc</C>,
      respectively,
</Item>
<Item>
 a point stabilizer of index 11 in <M>M_{11}</M>, denoted by <C>M10</C>.
</Item>
</List>
<P/>
As   mentioned      above,  the   data    assembled   by    the  function
<Ref Func="DisplayImfInvariants"/> are <Q>cheap data</Q> 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.
</Description>
</ManSection>


<ManSection>
<Func Name="ImfInvariants" Arg='dim, q[, z]'/>

<Description>
<Ref Func="ImfInvariants"/> returns  a record which provides some
<M>&ZZ;</M>-class invariants of the groups in the
<A>z</A>-th <M>&ZZ;</M>-class in the <A>q</A>-th <M>&QQ;</M>-class of
i.m.f.&nbsp;integral matrix groups of dimension <A>dim</A>.
A value <A>z</A> <M>\neq 1</M> must not be specified if the
<M>&ZZ;</M>-classes are not known for the given dimension, i.e.,
if <A>dim</A> <M>&gt; 11</M> and
<A>dim</A> <M>\not \in \{ 13, 17, 19, 23 \}</M>.
The default value of <A>z</A> is&nbsp;1.
This value of <A>z</A> will be accepted even if the <M>&ZZ;</M>-classes are
not known.
Then it specifies the only representative group which is available for the
<A>q</A>-th <M>&QQ;</M>-class.
The greatest legal value of <A>dim</A> is 31.
<P/>
The resulting record contains six or seven components:
<P/>
<List>
<Mark><C>size</C> </Mark>
<Item>
      the size of any representative group <A>G</A>,
</Item>
<Mark><C>isSolvable</C> </Mark>
<Item>
      is <K>true</K> if <A>G</A> is solvable,
</Item>
<Mark><C>isomorphismType</C> </Mark>
<Item>
      a text string describing the isomorphism type of  <A>G</A>  (in the same
      notation as used by the function <C>DisplayImfInvariants</C> above),
</Item>
<Mark><C>elementaryDivisors</C> </Mark>
<Item>
      the elementary divisors of the associated Gram matrix  <A>F</A>  (in the
      same format as the result of the function
      <Ref Oper="ElementaryDivisorsMat"/>,
</Item>
<Mark><C>minimalNorm</C> </Mark>
<Item>
      the norm of the associated short vectors,
</Item>
<Mark><C>sizesOrbitsShortVectors</C> </Mark>
<Item>
      the sizes of the orbits of short vectors under <A>F</A>,
</Item>
<Mark><C>maximalQClass</C> </Mark>
<Item>
      the  <M>&QQ;</M>-class  number  of  an  i.m.f.&nbsp;group  in  <M>GL_n(&QQ;)</M>  that
      contains <A>G</A> as a subgroup  (only in case that not <A>G</A> itself is an
      i.m.f.&nbsp;subgroup of <M>GL_n(&QQ;)</M>).
</Item>
</List>
<P/>
Note that four of these data, namely the group size, the solvability, the
isomorphism  type, and the   corresponding rational i.m.f.&nbsp;class, are not
only <M>&ZZ;</M>-class invariants, but also <M>&QQ;</M>-class invariants.
<P/>
Note further that, though the isomorphism type is a <M>&QQ;</M>-class invariant,
you will sometimes  get different descriptions for different <M>&ZZ;</M>-classes
of the same <M>&QQ;</M>-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.
<P/>
<Example><![CDATA[
gap> ImfInvariants( 8, 15, 1 );
rec( elementaryDivisors := [ 1, 3, 3, 3, 9, 9, 9, 27 ],
  isSolvable := true, isomorphismType := "C2 x (S3 wr S3)",
  maximalQClass := 5, minimalNorm := 8, size := 2592,
  sizesOrbitsShortVectors := [ 54 ] )
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)
]]></Example>
</Description>
</ManSection>


<ManSection>
<Func Name="ImfMatrixGroup" Arg='dim, q[, z]'/>

<Description>
<Ref Func="ImfMatrixGroup"/> is the essential extraction function of this
library (note that its name has been changed from <C>ImfMatGroup</C>
in &GAP;&nbsp;3 to <Ref Func="ImfMatrixGroup"/> in &GAP;&nbsp;4).
It returns a representative group, <M>G</M> say,
of the <A>z</A>-th <M>&ZZ;</M>-class in the <A>q</A>-th <M>&QQ;</M>-class of
i.m.f.&nbsp;integral matrix groups of dimension <A>dim</A>.
A value <A>z</A><M> \neq 1</M> must not be specified if the
<M>&ZZ;</M>-classes are not known for the given dimension, i.e.,
if <A>dim</A> <M>&gt; 11</M> and
<A>dim</A> <M>\not \in \{ 13, 17, 19, 23 \}</M>.
The default value of <A>z</A> is&nbsp;1.
This value of <A>z</A> will be accepted even if the <M>&ZZ;</M>-classes are
not known.
Then it specifies the only representative group which is available for the
<A>q</A>-th <M>&QQ;</M>-class.
The greatest legal value of <A>dim</A> is 31.
<P/>
<Example><![CDATA[
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 ] ]
]]></Example>
<P/>
The attributes <Ref Attr="Size"/> and <C>IsSolvable</C> will be
properly set in the resulting matrix group <M>G</M>.
In addition, it has two attributes <C>IsImfMatrixGroup</C> and
<C>ImfRecord</C> where the first one is just a logical flag set to
<K>true</K> 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
<Ref Func="ImfInvariants"/> described above, namely the components
<C>isomorphismType</C>, <C>elementaryDivisors</C>, <C>minimalNorm</C>,
and <C>sizesOrbitsShortVectors</C> and,
if <M>G</M> is not a rational i.m.f.&nbsp;group, <C>maximalQClass</C>.
Moreover, it has the two components
<P/>
<List>
<Mark><C>form</C></Mark>
<Item>
   the associated Gram matrix <M>F</M>, and
</Item>
<Mark><C>repsOrbitsShortVectors</C></Mark>
<Item>
   representatives of the orbits of short vectors under <M>F</M>.
</Item>
</List>
<P/>
The  last one  of  these  components  will be  required  by the  function
<Ref Meth="IsomorphismPermGroup" Label="for Imf matrix groups"/> below.
<P/>
<Example><![CDATA[
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
]]></Example>
<P/>
If you want to perform calculations in such a matrix group <M>G</M>
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
<M>G</M> on one of the orbits of the associated short vectors.
You may call one of the following functions
<Ref Meth="IsomorphismPermGroup" Label="for Imf matrix groups"/> or
<Ref Func="IsomorphismPermGroupImfGroup"/> to get an isomorphism to such a
permutation group (note that these &GAP;&nbsp;4 functions have replaced the
&GAP;&nbsp;3 functions <C>PermGroup</C> and <C>PermGroupImfGroup</C>).
</Description>
</ManSection>


<ManSection>
<Meth Name="IsomorphismPermGroup" Arg='G' Label="for Imf matrix groups"/>

<Description>
returns an isomorphism, <M>\varphi</M> say, from the given
i.m.f.&nbsp;integral matrix group <M>G</M> to a permutation group
<M>P := \varphi(G)</M> acting on a minimal orbit, <M>S</M> say,
of short vectors of <M>G</M> such that each matrix <M>m \in G</M> is mapped
to the permutation induced by its action on <M>S</M>.
<P/>
Note that in case of a large orbit the construction of <M>\varphi</M> may be
space and time consuming.
Fortunately, there are only six <M>&QQ;</M>-classes in the library for which
the smallest orbit of short vectors is of size greater than <M>20000</M>,
the worst case being the orbit of size <M>196560</M>
for the Leech lattice (<A>dim</A> <M>= 24</M>, <A>q</A> <M>= 3</M>).
<P/>
The inverse isomorphism <M>\varphi^{{-1}}</M> from <M>P</M> to <M>G</M> is
constructed by determining a <M>&QQ;</M>-base <M>B \subset S</M> of
<M>&QQ;^{{1 \times dim}}</M> in <M>S</M> and, in addition,
the associated base change matrix <M>M</M> which transforms <M>B</M> into the
standard base of <M>&ZZ;^{{1 \times dim}}</M>.
This allows a simple computation of the preimage <M>\varphi^{{-1}}(p)</M> of
any permutation <M>p \in P</M>, as follows.
If, for <M>1 \leq i \leq</M> <A>dim</A>,
<M>b_i</M> is the position number in <M>S</M> of the <M>i</M>-th base vector
in <M>B</M>,
it suffices to look up the vector whose position number in <M>S</M> is the
image of <M>b_i</M> under <M>p</M> and to multiply this vector by <M>M</M> to
get the <M>i</M>-th row of <M>\varphi^{{-1}}(p)</M>.
<P/>
You may use the functions
<Ref Func="Image" Label="set of images of the source of a general mapping"/>
and
<Ref Func="PreImage" Label="set of preimages of the range of a general mapping"/>
to switch from <M>G</M> to <M>P</M> and back from <M>P</M> to <M>G</M>.
<P/>
As an  example, let  us continue  the preceding example  and  compute the
solvable residuum of the group <M>G</M>.
<P/>
<Example><![CDATA[
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 );;
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 );;
gap> StructureDescription(R);
"(C2 x C2 x C2 x C2) : A5"
gap> IdGroup(D)=IdGroup(R);
true
]]></Example>
</Description>
</ManSection>


<ManSection>
<Func Name="IsomorphismPermGroupImfGroup" Arg='G, n'/>

<Description>
<Ref Func="IsomorphismPermGroupImfGroup"/> returns an isomorphism,
<M>\varphi</M> say, from the given i.m.f.&nbsp;integral matrix group <A>G</A>
to a permutation group <M>P</M> acting on the <A>n</A>-th orbit,
<M>S</M> say, of short vectors of <A>G</A> such that each matrix
<M>m \in</M> <A>G</A> is mapped to the permutation induced
by its action on <M>S</M>.
<P/>
The only difference to the above function
<Ref Meth="IsomorphismPermGroup" Label="for Imf matrix groups"/> 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 <C>IsomorphismPermGroup( <A>G</A> )</C> has been implemented
such that it is equivalent to
<C>IsomorphismPermGroupImfGroup( <A>G</A>, 1 )</C>.
<P/>
<Example><![CDATA[
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
]]></Example>
</Description>
</ManSection>

</Section>
</Chapter>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %E -->