%!TEX root = manual.in.tex
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  access.tex            IRREDSOL documentation            Burkhard Höfling
%%
%%  Copyright © 2003–2016 Burkhard Höfling 
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Chapter{Accessing the data library}

This chapter describes the design of the {\IRREDSOL} group library (see 
Section "Design of the group library") and the
 various ways of accessing groups in the data library.
It is possible to construct individual groups in the group library (see
Section~"Low level access functions"), or to search for groups with certain
properties (see Section~"Finding matrix groups with given properties"). 
Finally, there are functions for loading and unloading group data 
manually (see Section~"Loading and unloading group data manually").


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Design of the group library}\null

\index{IRREDSOL!database design}

To avoid redundancy, the package {\IRREDSOL} does not actually store 
lists of irreducible subgroups of $GL(<n>, <q>)$ but
only has lists ${\cal
A}_{n,q}$ of subgroups of $GL(<n>, <q>)$ such that

\beginlist%unordered 
\item{$\bullet$} each group in ${\cal A}_{n,q}$ is absolutely irreducible and
soluble

\item{$\bullet$} ${\cal A}_{n,q}$ contains a conjugate of each absolutely
irreducible soluble subgroup of $GL(n, q)$

\item{$\bullet$} no two groups in ${\cal A}_{n,q}$ are conjugate in  $GL(n, q)$

\item{$\bullet$} each group in ${\cal A}_{n,q}$ has trace field $\F_q$.

\endlist 
%
(For $n = 1$, such lists are not actually stored but are computed when required.)

We will briefly say that ${\cal A}_{n,q}$ contains, up to conjugacy, all absolutely
irreducible soluble subgroups of $GL(n,q)$ with trace field $\F_q$. 
Here, the {\it trace field} of a
subgroup $G$ of
$GL(n, q)$ is the field generated by the traces of the elements of~$G$. By a 
theorem of Brauer, an irreducible subgroup of $GL(n, q)$ with trace field $\F_{q_0}$ 
has a conjugate lying in $GL(n, q_0)$. See also `TraceField' ("TraceField")
and `ConjugatingMatTraceField' ("ConjugatingMatTraceField"). 

Note that by the Deuring-Noether theorem, two subgroups of $GL(n, q_0)$ are
conjugate in $GL(n, q_0)$ if, and only if, they are conjugate in $GL(n, q)$. Therefore, we obtain, up to conjugacy, all absolutely irreducible soluble subgroups of $GL(n, q)$ by forming the 
union of the ${\cal A}_{n, q_0}$, where $\F_{q_0}$ runs over all subfields of $\F_q$.

The lists ${\cal A}_{n, q}$ are also sufficient to reconstruct lists of all irreducible soluble subgroups of $GL(n, q)$. Let $d$ be a divisor of $n$, and let $G$ be an absolutely irreducible subgroup of $GL(n/d, q^d)$. By regarding the underlying $\F_{q^d}$-vector space of~$G$ as an $\F_q$-vector
space, we obtain an irreducible subgroup $G^\*$ of $GL(n, q)$ with splitting field $\F_{q^d}$. Up to conjugacy, all irreducible subgroups of $GL(n, q)$ arise in that way. If two subgroups $G_1$ and $G_2$ of $GL(n, q)$ are constructed from subgroups
$G_1^\*$ and $G_2^\*$ of $GL(n/d, q^d)$, then $G_1$ and $G_2$ are conjugate if, and only if, there exists a Galois automophism $\sigma$ of $\F_{q^d}/\F_q$ such that $(G_1^\*)^\sigma$ and $G_2^\*$ are conjugate in $GL(n/d, q^d)$. See, e.~g., \cite{DH}, Theorem B~5.15. The latter information has been precomputed and is also part of the {\IRREDSOL} library.

Note that all of the arguments above apply to nonsoluble groups as well.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Low level access functions}\null

\index{IRREDSOL!accessing low level data}

The access functions described in this section allow
to check for the availability of data and to construct
irreducible  groups in the {\IRREDSOL} group library.

\>`IsAvailableIrreducibleSolubleGroupData(<n>, <q>)'%
{IsAvailableIrreducibleSolubleGroupData}%
@{`IsAvailableIrreducibleSoluble\\GroupData'} F
\>`IsAvailableIrreducibleSolvableGroupData(<n>, <q>)'%
{IsAvailableIrreducibleSolvableGroupData}%
@{`IsAvailableIrreducibleSolvable\\GroupData'} F


This function tests whether the irreducible soluble subgroups of $GL(n,q)$ with trace
field $\F_q$ are part of the {\IRREDSOL} library.

\>`IndicesIrreducibleSolubleMatrixGroups(<n>, <q>, <d>)'%
{IndicesIrreducibleSolubleMatrixGroups}%
@{`Indices\\Irreducible\\Soluble\\Matrix\\Groups'} F
\>`IndicesIrreducibleSolvableMatrixGroups(<n>, <q>, <d>)'%
{IndicesIrreducibleSolvableMatrixGroups}%
@{`Indices\\Irreducible\\Solvable\\Matrix\\Groups'} F

Let <n> and  <d> be positive integers and <q> a prime power. This
function returns a set of integers parametrising the groups in the {\IRREDSOL} library
which are subgroups of $GL(n,q)$ with trace field $\F_q$
and splitting field $\F_{q^d}$. This set is empty unless <d> divides <n>. An error is 
raised if the relevant data is not available, cf. "IsAvailableIrreducibleSolubleGroupData".


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

\>`IrreducibleSolubleMatrixGroup(<n>, <q>, <d>, <k>)'%
{IrreducibleSolubleMatrixGroup}%
@{`Irreducible\\Soluble\\MatrixGroup'} F
\>`IrreducibleSolvableMatrixGroup(<n>, <q>, <d>, <k>)'%
{IrreducibleSolvableMatrixGroup}%
@{`Irreducible\\Solvable\\MatrixGroup'} F

Let <n>, <d> and <k> be  positive integers and <q> a prime power. This
function returns the irreducible soluble subgroup of $GL(n,q)$ with trace field $\F_q$, 
splitting field~$\F_{q^d}$, and index~<k>.
An error is raised if the relevant
data is not available, or if <k> is not in  
`IndicesIrreducibleSolubleMatrixGroups'(<n>, <q>, <d>); cf. "IsAvailableIrreducibleSolubleGroupData" and "IndicesIrreducibleSolubleMatrixGroups".
The groups returned have the attributes and properties described in
Chapter "Additional functionality for matrix groups" set to their appropriate values.


\>`IsAvailableAbsolutelyIrreducibleSolubleGroupData(<n>, <q>)'%
{IsAvailableAbsolutelyIrreducibleSolubleGroupData}%
@{`IsAvailableAbsolutelyIrreducibleSoluble\\GroupData'} F
\>`IsAvailableAbsolutelyIrreducibleolvableGroupData(<n>, <q>)'%
{IsAvailableAbsolutelyIrreducibleSolvableGroupData}%
@{`IsAvailableAbsolutelyIrreducibleolvable\\GroupData'} F

This function tests whether the
absolutely irreducible soluble subgroups of $GL(n,q)$ with trace field $\F_q$ are in the {\IRREDSOL} library.




\>`IndicesMaximalAbsolutelyIrreducibleSolubleMatrixGroups(<n>, <q>)'%
{IndicesMaximalAbsolutelyIrreducibleSolubleMatrixGroups}%
@{`IndicesMaximalAbsolutelyIrreducible\\Soluble\\MatrixGroups'} F
\>`IndicesMaximalAbsolutelyIrreducibleSolvableMatrixGroups(<n>, <q>)'%
{IndicesMaximalAbsolutelyIrreducibleSolvableMatrixGroups}%
@{`IndicesMaximalAbsolutelyIrreducible\\Solvable\\MatrixGroups'} F

Let <n> be a  positive integer and <q> a prime power. This
function returns a set of integers parametrising those subgroups of $GL(n, q)$ in the
{\IRREDSOL} library that are maximal among the absolutely irreducible soluble subgroups with  trace field~$\F_q $ and that are maximal with
respect to being soluble. An error is raised if the relevant
data is not available (see "IsAvailableAbsolutelyIrreducibleSolubleGroupData" for information 
how to check this first). An integer <k> in the list return corresponds to `IrreducibleSolubleMatrixGroup'(<n>, <q>, 1, <k>), which is the same group as
`AbsolutelyIrreducibleSolubleMatrixGroup'(<n>, <q>, <k>).

\beginexample
gap> inds := IndicesMaximalAbsolutelyIrreducibleSolubleMatrixGroups(2,3);
[ 2 ] 
gap> IrreducibleSolubleMatrixGroup(2,3,1,2) = GL(2,3); # it is the whole GL
true
\endexample


\>`IndicesAbsolutelyIrreducibleSolubleMatrixGroups(<n>, <q>)'%
{IndicesAbsolutelyIrreducibleSolubleMatrixGroups}%
@{`IndicesAbsolutelyIrreducible\\Soluble\\MatrixGroups'} F
\>AbsolutelyIrreducibleSolubleMatrixGroup(<n>, <q>,  <k>) F

These functions are deprecated.  Please use `IndicesIrreducibleSolubleMatrixGroups'(<n>, <q>, 1) and `Ir\-re\-du\-ci\-ble\-Soluble\-MatrixGroup'(<n>, <q>, 1, <k>) instead.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Finding matrix groups with given properties}\null

\index{find!matrix group}
\index{matrix group!with given properties}


This section describes three functions
(`AllIrreducibleSolubleMatrixGroups',
`OneIrreducibleSolubleMatrixGroup',
`IteratorIrreducibleSolubleMatrixGroups') which allow to find matrix
groups with prescribed properties. Using these functions can be more efficient
than to construct each group in the library using the functions in Section
"Low level access functions" because they can access additional information 
about a group in the {\IRREDSOL} library before actually constructing the group. 
See the discussion following the description of 
`AllIrreducibleSolubleMatrixGroups' for details. 

\>AllIrreducibleSolubleMatrixGroups(<func_1>, <arg_1>, <func_2>, <arg_2>, \dots) F
\>AllIrreducibleSolvableMatrixGroups(<func_1>, <arg_1>, <func_2>, <arg_2>, \dots) F
\>AllIrredSolMatGroups(<func_1>, <arg_1>, <func_2>, <arg_2>, \dots) F

This function returns a list of all irreducible soluble matrix
groups <G> in the {\IRREDSOL} library for which the return value of $<func_i>(G)$ lies in
<arg_i>.  The arguments <func_1>, <func_2>, \dots,
must be {\GAP} functions which take a matrix group as their only argument and
return a value, and <arg_1>, <arg_2>,
\dots,  must be lists. If <arg_i> is not a list, <arg_i> is replaced by the list
`['<arg_i>`]'. The functions `DegreeOfMatrixGroup' and `FieldOfMatrixGroup' (or their equivalents, see below) must be among the <func_i>. 
`TraceField'). Note that all groups in the data library have the property that 
$`TraceField'(<G>) = `FieldOfMatrixGroup'(<G>)$; see Section~"Design of the group library" 
for details. 

Note that there is also a function `IteratorIrreducibleSolubleMatrixGroups' (see
"IteratorIrreducibleSolubleMatrixGroups") which allows to run through the list produced by
`AllIrreducibleSolubleMatrixGroups' without having to store all of the groups
simultaneously.

The following functions <func_i> are handled particularly efficiently, because the
return values of these functions can be read off the
{\IRREDSOL} library without actually constructing the relevant matrix group. For the
definitions of these functions, see Chapter~"Additional functionality for matrix
groups".

\beginlist%unordered 

\item{$\bullet$} `DegreeOfMatrixGroup' (or `Degree', `Dimension',
`DimensionOfMatrixGroup'), 
\item{$\bullet$} `CharacteristicOfField' (or `Characteristic')
\item{$\bullet$} `FieldOfMatrixGroup' (or `Field' or `TraceField')
\item{$\bullet$} `Order' (or `Size')
\item{$\bullet$} `IsMaximalAbsolutelyIrreducibleSolubleMatrixGroup' 
\item{$\bullet$} `IsAbsolutelyIrreducibleMatrixGroup' (or
`IsAbsolutelyIrreducible')
\item{$\bullet$} `MinimalBlockDimensionOfMatrixGroup' (or
`MinimalBlockDimension')
\item{$\bullet$} `IsPrimitiveMatrixGroup' (or `IsPrimitive',
`IsLinearlyPrimitive')

\endlist
The groups <G> passed to the <func_i> and the groups returned have the attributes and properties described in 
Chapter~"Additional functionality for matrix groups" set to their appropriate values.
Note that you may speed up computations in <G> by using an isomorphic copy of <G>, which can be obtained via `RepresentationIsomorphism' (see "RepresentationIsomorphism").

\beginexample
# get just those groups with trace field GF(9)
gap> l := AllIrreducibleSolubleMatrixGroups(Degree, 1, Field, GF(9));;
gap> List(l, Order);
[ 4, 8 ]

# get all irreducible subgroups
gap> l := AllIrreducibleSolubleMatrixGroups(Degree, 1, Field, Subfields(GF(9)));;
gap> List(l, Order);
[ 1, 2, 4, 8 ]

# get only maximal absolutely irreducible ones
gap> l := AllIrreducibleSolubleMatrixGroups(Degree, 4, Field, GF(3),
>             IsMaximalAbsolutelyIrreducibleSolubleMatrixGroup, true);;
gap> SortedList(List(l, Order));
[ 320, 640, 2304, 4608 ]

# get only absolutely irreducible groups
gap> l := AllIrreducibleSolubleMatrixGroups(Degree, 4, Field, GF(3),
> IsAbsolutelyIrreducibleMatrixGroup, true);;
gap> Collected(List(l, Order));
[ [ 20, 1 ], [ 32, 7 ], [ 40, 2 ], [ 64, 10 ], [ 80, 2 ], [ 96, 6 ], 
  [ 128, 9 ], [ 160, 3 ], [ 192, 9 ], [ 256, 6 ], [ 288, 1 ], [ 320, 2 ], 
  [ 384, 4 ], [ 512, 1 ], [ 576, 3 ], [ 640, 1 ], [ 768, 1 ], [ 1152, 4 ], 
  [ 2304, 3 ], [ 4608, 1 ] ]
\endexample

\>OneIrreducibleSolubleMatrixGroup(<func_1>, <arg_1>, <func_2>, <arg_2>, \dots) F
\>OneIrreducibleSolvableMatrixGroup(<func_1>, <arg_1>, <func_2>, <arg_2>, \dots) F
\>OneIrredSolMatGroup(<func_1>, <arg_1>, <func_2>, <arg_2>, \dots) F

This function returns a matrix group <G> from the {\IRREDSOL} library such that
$<func_i>(G)$ lies in <arg_i>, or `fail' if no such group exists. The arguments <func_1>,
<func_2>, \dots, must be {\GAP} functions taking one argument and returning a value, and
<arg_1>, <arg_2>, \dots,  must be lists. If <arg_i> is not a list, <arg_i> is replaced by
the list `['<arg_i>`]'. The functions `DegreeOfMatrixGroup' and `FieldOfMatrixGroup' (or their equivalents, see below) must be among the <func_i>. 
 Note that all groups in the data library have the property that 
$`TraceField'(<G>) = `FieldOfMatrixGroup'(<G>)$; see Section~"Design of the group library" 
for details. 
The groups passed to the <func_i> and the groups returned have the attributes and properties described in 
Chapter~"Additional functionality for matrix groups" set to their appropriate values.

To use this function efficiently, please see the comments in 
"AllIrreducibleSolubleMatrixGroups".


\>IteratorIrreducibleSolubleMatrixGroups(<func_1>, <arg_1>, <func_2>, <arg_2>, \dots) F
\>IteratorIrreducibleSolvableMatrixGroups(<func_1>, <arg_1>, <func_2>, <arg_2>, \dots) F
\>IteratorIrredSolMatGroups(<func_1>, <arg_1>, <func_2>, <arg_2>, \dots) F

This function returns an iterator which runs through the list of all matrix groups <G>
in the  {\IRREDSOL} library such that
$<func_i>(G)$ lies in <arg_i>. The arguments <func_1>, <func_2>, \dots,
must be {\GAP} functions taking one argument and returning a value, and <arg_1>, <arg_2>, \dots, 
must be lists. If <arg_i> is not a list, <arg_i> is replaced by the list `['<arg_i>`]'.
The functions `DegreeOfMatrixGroup' and `FieldOfMatrixGroup' (or their equivalents, see below) must be among the <func_i>. 


Using 

`IteratorIrreducibleSolubleMatrixGroups'(<func_1>, <arg_1>, <func_2>, <arg_2>, \dots)) 

is functionally equivalent to 

`Iterator'(`AllIrreducibleSolubleMatrixGroups'(<func_1>, <arg_1>, <func_2>, <arg_2>, \dots))

(see Section~"ref:Iterators" in the {\GAP} reference manual for details) but, unlike `AllIrreducibleSolubleMatrixGroups', does not store all 
relevant matrix groups at the same time. This may save a considerable amount of memory. 

To use this function efficiently, please see the comments in 
"AllIrreducibleSolubleMatrixGroups".


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Loading and unloading group data manually}\null

\index{loading!of group data}
\index{unloading!of group data}

The data required by the {\IRREDSOL} library is loaded into {\GAP}'s workspace automatically whenever required, but is never unloaded automatically. The functions described in this
and the following section describe how to load and unload this data manually. 
They are only relevant if timing or conservation of memory is an issue.
\index{workspace!running out of}

\>LoadAbsolutelyIrreducibleSolubleGroupData(<n>, <q>) F
\>LoadAbsolutelyIrreducibleSolvableGroupData(<n>, <q>) F
\>LoadAbsoIrredSolGroupData(<n>, <q>) F

This function loads the data for $GL(<n>, <q>)$ into the {\GAP} workspace and does 
some pre-processing. If the data is already loaded, the function does nothing. This 
function is called automatically when you access the
{\IRREDSOL} library, so most users  will not need this function.

\>`LoadedAbsolutelyIrreducibleSolubleGroupData()'%
{LoadedAbsolutelyIrreducibleSolubleGroupData}%
@{`LoadedAbsolutelyIrreducibleSoluble\\GroupData'} F
\>`LoadedAbsolutelyIrreducibleSolvableGroupData()'%
{LoadedAbsolutelyIrreducibleSolvableGroupData}%
@{`LoadedAbsolutelyIrreducibleSolvable\\GroupData'} F
\>LoadedAbsoIrredSolGroupData(<n>, <q>) F

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

\>`UnloadAbsolutelyIrreducibleSolubleGroupData([<n> [, <q>]])'%
{UnloadAbsolutelyIrreducibleSolubleGroupData}%
@{`UnloadAbsolutelyIrreducibleSoluble\\GroupData'} F
\>`UnloadAbsolutelyIrreducibleSolvableGroupData([<n> [, <q>]])'%
{UnloadAbsolutelyIrreducibleSolvableGroupData}%
@{`UnloadAbsolutelyIrreducibleSolvable\\GroupData'} F
\>UnloadAbsoIrredSolGroupData(<n>, <q>) F

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


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