%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  primitive.tex         IRREDSOL documentation           Burkhard H\"ofling
%%
%%  @(#)$Id: primitive.tex,v 1.1 2003/07/29 10:51:31 gap Exp $
%%
%%  Copyright (C) 2003 by Burkhard H\"ofling, 
%%  Institut f\"ur Geometrie, Algebra und Diskrete Mathematik
%%  Technische Universit\"at Braunschweig, Germany
%%


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Chapter{Primitive solvable groups}

A finite group <G> is primitive if it has a maximal subgroup <M> with 
trivial core; the group acts primitively on the cosets of such
a maximal subgroup.  If <G> is solvable, there is a unique conjugacy class of 
such maximal subgroups; the index of <M> in <G> is called the degree of <G>.
The degree of <G> is always a prime power, $<p>^<n>$, say. There exists a well known
bijection between the isomorphpism types of primitive solvable groups of degree
$<p>^<n>$ and the conjugacy classes of irreducible subgrups of $GL(n, p)$.

The {\IRREDSOL} package provides functions for performing these translations,
described in "Translating irreducible solvable matrix groups into primitive
solvable groups and back". Moreover, there are functions for finding
primitive solvable groups with given properties, see "Finding primitive solvable groups
with given properties".



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Translating irreducible solvable matrix groups into primitive
solvable groups and back}

\>PrimitivePcGroupIrreducibleMatrixGroup(<G>) F
\>PrimitivePcGroupIrreducibleMatrixGroupNC(<G>) F

For a given irreducible solvable matrix group G over a prime field, this function
returns a primitive pc group which is the split extension of G with its natural
underlying vector space. The NC version does not check whether G is over a prime field, 
or whether G is irreducible.

\>IrreducibleMatrixGroupPrimitivePcGroup(<G>) F
\>IrreducibleMatrixGroupPrimitivePcGroupNC(<G>) F

For a given primitive solvable group <G>, this function returns the corresponding
irreducible matrix group, that is, the matrix group obtained from the conjugation
action of <G> on its unique minimal normal subgroup <N>, regarded as a vector 
space over $GF(p)$, where $p$ is the exponent of <N>.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Finding primitive solvable groups with given properties}


\>AllPrimitivePcGroups(<func_1>, <arg_1>, <func_2>, <arg_2>, \dots) F

This function returns a list of all primitive solvable 
groups <G> in the  {\IRREDSOL} librar 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 pc 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>]'. One of the functions must be `Degree' (or one of its
equivalents, see below).

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

The following functions <func_i> are handled particularly efficiently. 

\beginlist

\item{--} `Degree', `NrMovedPoints', `LargestMovedPoint'
\item{--} `Order', `Size'
\endlist

\>OnePrimitivePcGroup(<func_1>, <arg_1>, <func_2>, <arg_2>, \dots) F

This function returns one primitive solvable 
groups <G> in the  {\IRREDSOL} librarfor which the return value of $<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 which take pc 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>]'. One of the functions must be `Degree'.

For a list of functions which are handled particularly efficiently, see
`AllPrimitivePcGroups' ("AllPrimitivePcGroups").

\>IteratorPrimitivePcGroups(<func_1>, <arg_1>, <func_2>, <arg_2>, \dots) F

This function returns an iterator which runs through the list of all primitive solvable
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>]'.
One of the functions must be `Degree'.
For a list of functions which are handled particularly efficiently, see
`AllPrimitivePcGroups' ("AllPrimitivePcGroups").

Using 

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

is functionally equivalent to 

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

(see "ref:Iterators" for details) but does not compute all relevant matrix groups at the same time. 
This may save some memory. 





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