% This file was created automatically from pcgs.msk.
% DO NOT EDIT!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%A  pcgs.msk                    GAP documentation            Alexander Hulpke
%A                                                               Bettina Eick
%%
%A  @(#)$Id: pcgs.msk,v 1.33 2003/01/30 17:23:11 gap Exp $
%%
%Y  (C) 1998 School Math and Comp. Sci., University of St.  Andrews, Scotland
%Y  Copyright (C) 2002 The GAP Group
%%
\Chapter{Polycyclic Groups}

A group <G> is *polycyclic* if there exists a subnormal series
$G = C_1 > C_2 > \ldots > C_n > C_{n+1} = \{1\}$
with cyclic factors. Such a series is called *pc series* of <G>.

Every polycyclic group is solvable and every finite solvable group
is polycyclic. However, there are infinite solvable groups which
are not polycyclic.

In {\GAP} there exists a large number of methods for polycyclic groups
which are based upon the polycyclic structure of these groups. These
methods are usually very efficient and hence {\GAP} tries to use them
whenever possible.

In {\GAP}~3 these methods have been available for AgGroups only; that
is, for groups defined via a power-commutator presentation, see
Chapter~"Pc Groups" for the {\GAP}~4 analogon. This has changed in {\GAP}~4
where these methods can be applied to many types of groups. For example,
the methods can be applied to permutation groups or matrix groups which
are known to be polycyclic. The only exception is the representation as
finitely presented group for which the polycyclic methods cannot
be used in general.

At the current state of implementations the methods for polycyclic
groups can only be applied to finite groups. However, a more general
implementation is planned.

%%  Most of the methods for polycyclic groups are due to Frank Celler, Bettina
%%  Eick, Alexander Hulpke and Werner Nickel. The methods to consider a solvable
%%  permutation group as a polycyclic group are due to Heiko Thei{\ss}en.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Polycyclic Generating Systems}

Let <G> be a polycyclic group with a pc series as above.  A
*polycyclic generating sequence* (*pcgs* for short) of <G> is a
sequence $P := (g_1, \ldots, g_n)$ of elements of <G> such that
$C_i = \langle C_{i+1}, g_i \rangle$ for $1 \leq i \leq n$.
Note that each polycyclic group has a pcgs, but except for very
small groups, a pcgs is not unique.

For each index $i$ the subsequence of elements $(g_i, \ldots, g_n)$
forms a pcgs of the subgroup $C_i$. In particular, these *tails*
generate the subgroups of the pc series and hence we say that
the pc series is *determined* by $P$.

Let $r_i$ be the index of $C_{i+1}$ in $C_i$ which is either
a finite positive number or infinity. Then $r_i$ is the order of
$g_i C_{i+1}$ and we call the resulting list of indices the
*relative orders* of the pcgs <P>.

Moreover, with respect to a given pcgs $(g_1, \ldots, g_n)$ each
element <g> of <G> can be represented in a unique
way as a product $g = g_1^{e_1} \cdot g_2^{e_2} \cdots g_n^{e_n}$
with exponents $e_i \in \{0, \ldots, r_i-1\}$, if $r_i$ is finite,
and $e_i \in \Z$ otherwise.
Words of this form are called *normal words* or *words in normal form*.
Then the integer vector $[e_1, \ldots, e_n]$ is called the
*exponent vector* of the element $g$. Furthermore, the smallest
index $k$ such that $e_k \neq 0$ is called the *depth* of <g> and
$e_k$ is the *leading exponent* of <g>.

For many applications we have to assume that each of the relative orders
$r_i$ is either a prime or infinity. This is equivalent to saying that
there are no trivial factors in the pc series and the finite factors of the
pc series are maximal refined. Then we obtain that $r_i$ is the order of
$g C_{i+1}$ for all elements $g$ in $C_i \setminus C_{i+1}$ and we call
$r_i$ the *relative order* of the element $g$.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Computing a Pcgs}

Suppose a group <G> is given; for example, let <G> be a permutation
or matrix group. Then we can ask {\GAP} to compute a pcgs of this group.
If <G> is not polycyclic, the result will be `fail'.

Note that these methods can only be applied if <G> is not given
as finitely presented group. For finitely presented groups one
can try to compute a pcgs via the polycyclic quotient methods,
see "Quotient Methods".

Note also that a pcgs behaves like a list.

\>Pcgs( <G> ) A

returns a pcgs for the group <G>. 
If <grp> is not polycyclic it returns `fail' *and this result is not 
stored as attribute value*, in particular in this case the filter
`HasPcgs' is *not* set for <G>!

\>IsPcgs( <obj> ) C

The category of pcgs. 


\beginexample
gap> G := Group((1,2,3,4),(1,2));;
gap> p := Pcgs(G);
Pcgs([ (3,4), (2,4,3), (1,4)(2,3), (1,3)(2,4) ])
gap> IsPcgs( p );
true
gap> p[1];
(3,4)
\endexample

\beginexample
gap> G := Group((1,2,3,4,5),(1,2));;
gap> Pcgs(G);
fail
\endexample

\>CanEasilyComputePcgs( <grp> ) F

This filter indicates whether it is possible to compute a pcgs for <grp>
cheaply. Clearly, <grp> must be polycyclic in this case. However, not
for every polycyclic group there is a method to compute a pcgs at low
costs. This filter is used in the method selection mainly.
Note that this filter may change its value from false to true. 



\beginexample
gap> G := Group( (1,2,3,4),(1,2) );
Group([ (1,2,3,4), (1,2) ])
gap> CanEasilyComputePcgs(G);
false
gap> Pcgs(G);
Pcgs([ (3,4), (2,4,3), (1,4)(2,3), (1,3)(2,4) ])
gap> CanEasilyComputePcgs(G);
true
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Defining a Pcgs Yourself}

In a number of situations it might be useful to supply a pgcs
to a group.

\>PcgsByPcSequence( <fam>, <pcs> ) O
\>PcgsByPcSequenceNC( <fam>, <pcs> ) O

constructs a pcgs for the elements family <fam> from the elements in the
list <pcs>. The elements must lie in the family <fam>.
`PcgsByPcSequence'(`NC') will always create a new pcgs which is not
induced by any other pcgs.


\beginexample
gap> fam := FamilyObj( (1,2) );; # the family of permutations
gap> p := PcgsByPcSequence( fam, [(1,2),(1,2,3)] );
Pcgs([ (1,2), (1,2,3) ])
gap> RelativeOrders(p);
[ 2, 3 ]
gap> ExponentsOfPcElement( p, (1,3,2) );
[ 0, 2 ]
\endexample

Note that the elementary operations for such a pcgs might be rather
inefficient, since {\GAP} has to use generic methods in this case.
It might be helpful to supply the relative orders of the self-defined
pcgs as well by `SetRelativeOrders( pcgs, orders )'.
See also~"IsPrimeOrdersPcgs".

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Elementary Operations for a Pcgs}

\>RelativeOrders( <pcgs> )!{of a pcgs} A

returns the list of relative orders of the pcgs <pcgs>.


the list of relative orders of the pcgs <pcgs>.

\>IsFiniteOrdersPcgs( <pcgs> ) P

tests whether the relative orders of <pcgs> are all finite.

\>IsPrimeOrdersPcgs( <pcgs> ) P

tests whether the relative orders of <pcgs> are prime numbers. 
Many algorithms require a pcgs to have this property. The
operation~`IsomorphismRefinedPcGroup' (see~"IsomorphismRefinedPcGroup")
can be of help here.

\>PcSeries( <pcgs> ) A

returns the subnormal series determined by <pcgs>.

\>GroupOfPcgs( <pcgs> ) A

The group generated by <pcgs>.

\>OneOfPcgs( <pcgs> ) A

The identity of the group generated by <pcgs>.


\beginexample
gap> G := Group( (1,2,3,4),(1,2) );; p := Pcgs(G);;
gap> RelativeOrders(p);
[ 2, 3, 2, 2 ]
gap> IsFiniteOrdersPcgs(p);
true
gap> IsPrimeOrdersPcgs(p);
true
gap> PcSeries(p);
[ Group([ (3,4), (2,4,3), (1,4)(2,3), (1,3)(2,4) ]), 
  Group([ (2,4,3), (1,4)(2,3), (1,3)(2,4) ]), 
  Group([ (1,4)(2,3), (1,3)(2,4) ]), Group([ (1,3)(2,4) ]), Group(()) ]
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Elementary Operations for a Pcgs and an Element}

\>RelativeOrderOfPcElement( <pcgs>, <elm> ) O

The relative order of <elm> with respect to the prime order pcgs <pcgs>.

\>ExponentOfPcElement( <pcgs>, <elm>, <pos> ) O

returns the <pos>-th exponent of <elm> with respect to <pcgs>.

\>ExponentsOfPcElement( <pcgs>, <elm> ) O
\>ExponentsOfPcElement( <pcgs>, <elm>, <posran> ) O

returns the exponents of <elm> with respect to <pcgs>. The second form
returns the exponents in the positions given in <posran>.

\>DepthOfPcElement( <pcgs>, <elm> ) O

returns the depth of the element <elm> with respect to <pcgs>.

\>LeadingExponentOfPcElement( <pcgs>, <elm> ) O

returns the leading exponent of <elm> with respect to <pcgs>.

\>PcElementByExponents( <pcgs>, <list> ) O
\>PcElementByExponentsNC( <pcgs>, <list> ) O
\>PcElementByExponentsNC( <pcgs>, <basisind>, <list> ) O

returns the element corresponding to the exponent vector <list> with
respect to <pcgs>. The exponents in <list> must be in the range of
permissible exponents for <pcgs>. *It is not guaranteed that
`PcElementByExponents' will reduce the exponents modulo the relative
orders*. (You should use the operation `LinearCombinationPcgs' for this
purpose.) The NC version does not check that the lengths of the
lists fit together and does not check the exponent range.

The third version gives exponents only wrt. the generators in <pcgs>
indexed by <basisind>.

\>LinearCombinationPcgs( <pcgs>, <list> [, <one>] ) O

returns the product $\prod_i<pcgs>[i]^{<list>[i]}$. In contrast to
`PcElementByExponents' this permits negative exponents.
<pcgs> might be an list of group elements, in this case, an appropriate
<one> must be given. if <list> can be empty.


\beginexample
gap> G := Group( (1,2,3,4),(1,2) );; P := Pcgs(G);;
gap> g := PcElementByExponents(P, [0,1,1,1]);
(1,2,3)
gap> ExponentsOfPcElement(P, g);
[ 0, 1, 1, 1 ]
\endexample

\>SiftedPcElement( <pcgs>, <elm> ) O

sifts <elm> through <pcgs>, reducing it if the depth is the same as the
depth of one of the generators in <pcgs>. Thus the identity is returned
if <elm> lies in the group generated by <pcgs>.
<pcgs> must be an induced pcgs and <elm> must lie in the span of the
parent of <pcgs>.

\>CanonicalPcElement( <ipcgs>, <elm> ) O

reduces <elm> at the induces pcgs <ipcgs> such that the exponents of the
reduced result <r> are zero at the depths for which there are generators
in <ipcgs>. Elements, whose quotient lies in the group generated by
<ipcgs> yield the same canonical element.

\>ReducedPcElement( <pcgs>, <x>, <y> ) O

reduces the element <x> by dividing off (from the left) a power of <y>
such that the leading coefficient of the result with respect to <pcgs>
becomes zero. The elements <x> and <y> therefore have to have the same
depth.


\>CleanedTailPcElement( <pcgs>, <elm>, <dep> ) O

returns an element in the span of <pcgs> whose exponents for indices 1
to $<dep>-1$ with respect to <pcgs> are the same as those of <elm>, the
remaining exponents are undefined. This can be used to obtain more
``simple'' elements if only representatives in a factor are required,
see~"Factor Groups of Polycyclic Groups - Modulo Pcgs".

The difference to `HeadPcElementByNumber' (see~"HeadPcElementByNumber")
is that `HeadPcElementByNumber' is guaranteed to zero out trailing
coefficients while `CleantedTailPcElement' will only do this if it can be
done cheaply.

\>HeadPcElementByNumber( <pcgs>, <elm>, <dep> ) O

returns an element in the span of <pcgs> whose exponents for indices 1
to $<dep>-1$ with respect to <pcgs> are the same as those of <elm>, the
remaining exponents are zero.
This can be used to obtain more
``simple'' elements if only representatives in a factor are required.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Exponents of Special Products}

There are certain products of elements whose exponents are used often within
algorithms, and which might be obtained more easily than by computing the
product first and to obtain its exponents afterwards. The operations in this
section provide a way to obtain such exponent vectors directly.

(The circumstances under which these operations give a speedup depend very
much on the pcgs and the representation of elements that is used. So the
following operations are not guaranteed to give a speedup in every case,
however the default methods are not slower than to compute the exponents of
a product and thus these operations should *always* be used if applicable.)

\>ExponentsConjugateLayer( <mpcgs>, <elm>, <e> ) O

Computes the exponents of $<elm>^<e>$ with respect to <mpcgs>; <elm>
must be in the span of <mpcgs>, <e> a pc element in the span of the
parent pcgs of <mpcgs> and <mpcgs> must be the modulo pcgs for
an abelian layer. (This is the usual case when acting on a chief
factor). In this case if <mpcgs> is induced by the family pcgs, the
exponents can be computed directly by looking up exponents without
having to compute in the group and having to collect a potential tail.



The second class are exponents of products of the generators which make up
the pcgs. If the pcgs used is a `FamilyPcgs' these exponents can be looked
up and do not need to be computed.
\>ExponentsOfRelativePower( <pcgs>, <i> ) O

For $<p>=<pcgs>[<i>]$ this function returns the exponent vector with
respect to <pcgs> of the element $p^e$ where <e> is the relative order of
<p> in <pcgs>.  For the family pcgs or pcgs induced by it, this might be
faster than computing the element and computing its exponent vector.

\>ExponentsOfConjugate( <pcgs>, <i>, <j> ) O

returns the exponents of $<pcgs>[<i>]^<pcgs>[<j>]$ with respect to
<pcgs>. For the family pcgs or pcgs induced by it, this might be faster
than computing the element and computing its exponent vector.

\>ExponentsOfCommutator( <pcgs>, <i>, <j> ) O

returns the exponents of the commutatior Comm($<pcgs>[<i>],<pcgs>[<j>]$)
with respect to <pcgs>. For the family pcgs or pcgs induced by it, this
might be faster than computing the element and computing its exponent
vector.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Subgroups of Polycyclic Groups - Induced Pcgs}

Let <U> be a subgroup of <G> and let <P> be a pcgs of <G> as above such
that <P> determines the subnormal series $G = C_1 > \ldots > C_{n+1} =
\{1\}$. Then the series of subgroups $U \cap C_i$ is a subnormal series
of <U> with cyclic or trivial factors. Hence, if we choose an element
$u_{i_j} \in (U \cap C_{i_j}) \setminus (U \cap C_{i_j+1})$ whenever
this factor is non-trivial, then we obtain a pcgs $Q = (u_{i_1}, \ldots,
u_{i_m})$ of $U$. We say that $Q$ is an *induced pcgs* with respect to
<P>. The pcgs <P> is the *parent pcgs* to the induced pcgs <Q>.

Note that the pcgs $Q$ is induced with respect to <P> if and only
if the matrix of exponent vectors of the elements $u_{i_j}$ with
respect to <P> is in upper triangular form. Thus $Q$ is not unique in
general.

In particular, the elements of an induced pcgs do *not necessarily* have
leading coefficient 1 relative to the inducing pcgs. The attribute
`LeadCoeffsIGS' (see~"LeadCoeffsIGS") holds the leading coefficients in case
they have to be renormed in an algorithm.

Each induced pcgs is a pcgs and hence allows all elementary operations
for pcgs. On the other hand each pcgs could be transformed into an
induced pcgs for the group defined by the pcgs, but note that an
arbitrary pcgs is in general not an induced pcgs for technical reasons.

An induced pcgs is ``compatible'' with its parent.

\>IsInducedPcgs( <pcgs> ) C

The category of induced pcgs. This a subcategory of pcgs.

\>InducedPcgsByPcSequence( <pcgs>, <pcs> ) O
\>InducedPcgsByPcSequenceNC( <pcgs>, <pcs> ) O
\>InducedPcgsByPcSequenceNC( <pcgs>, <pcs>, <depths> ) O

If <pcs> is a list of elements that form an induced pcgs with respect to
<pcgs> this operation returns an induced pcgs with these elements.

In the third version, the depths of <pcs> with respect to <pcgs> can be
given (they are computed anew otherwise).

\>ParentPcgs( <pcgs> ) A

returns the pcgs by which <pcgs> was induced. If <pcgs> was not induced,
it simply returns <pcgs>.


\beginexample
gap> G := Group( (1,2,3,4),(1,2) );;
gap> P := Pcgs(G);;
gap> K := InducedPcgsByPcSequence( P, [(1,2,3,4),(1,3)(2,4)] );
Pcgs([ (1,2,3,4), (1,3)(2,4) ])
gap> ParentPcgs( K );
Pcgs([ (3,4), (2,4,3), (1,4)(2,3), (1,3)(2,4) ])
gap> IsInducedPcgs( K );
true
\endexample

In \cite{SOGOS} a ``non-commutative gauss'' algorithm is
described to compute an induced pcgs of a subgroup <U>  from a
generating set of <U>. This can be called in {\GAP} via one of the
following commands.

\>InducedPcgs( <pcgs>, <grp> ) O

computes a pcgs for <grp> which is induced by <pcgs>. If <pcgs> has
a parent pcgs, then the result is induced with respect to this parent
pcgs.

`InducedPcgs' is a wrapper function only. Therefore, methods for computing 
computing an induced pcgs should be installed for the
operation `InducedPcgsOp'.


\>InducedPcgsByGenerators( <pcgs>, <gens> ) O
\>InducedPcgsByGeneratorsNC( <pcgs>, <gens> ) O

returns an induced pcgs with respect to <pcgs> for the subgroup generated
by <gens>.

\>InducedPcgsByPcSequenceAndGenerators( <pcgs>, <ind>, <gens> ) O

returns an induced pcgs with respect to <pcgs> of the subgroup generated
by <ind> and <gens>. Here <ind> must be an induced pcgs with respect to
<pcgs> (or a list of group elements that form such an igs) and it will
be used as initial sequence for the computation.


\beginexample
gap> G := Group( (1,2,3,4),(1,2) );;  P := Pcgs(G);;
gap> I := InducedPcgsByGenerators( P, [(1,2,3,4)] );
Pcgs([ (1,2,3,4), (1,3)(2,4) ])
gap> J := InducedPcgsByPcSequenceAndGenerators( P, I, [(1,2)] );
Pcgs([ (1,2,3,4), (2,4,3), (1,4)(2,3), (1,3)(2,4) ])
\endexample

\>LeadCoeffsIGS( <igs> ) A

This attribute is used to store leading coefficients with respect to the
parent pcgs. the <i>-th entry - if bound - is the leading exponent of
the element of <igs> that has depth <i> in the parent.  (It cannot be
assigned to a component in `InducedPcgsByPcSequenceNC' as the
permutation group methods call it from within the  postprocessing,
before this postprocessing however no coefficients may be computed.)


\>ExtendedPcgs( <N>, <gens> ) O

extends the pcgs <N> (induced wrt. <home>) to a new induced pcgs by
prepending <gens>. No checks are performed that this really yields an
induced pcgs.


To create a subgroup generated by an induced pcgs such that the
induced pcgs gets stored automatically there is the following
operation.

\>SubgroupByPcgs( <G>, <pcgs> ) O



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Subgroups of Polycyclic Groups - Canonical Pcgs}

The induced pcgs <Q> of <U> is called *canonical* if the matrix
of exponent vectors contains normed vectors only and above each
leading entry in the matrix there are 0's only.  The canonical pcgs
of <U> with respect to <P> is unique and hence such pcgs can be used
to compare subgroups.

\>IsCanonicalPcgs( <pcgs> ) P

An induced pcgs is canonical if the matrix of the exponent vectors of
the elements of <pcgs> with respect to `ParentPcgs(<pcgs>)' is in
Hermite normal form
(see \cite{SOGOS}). While a subgroup can have various
induced pcgs with respect to a parent pcgs a canonical pcgs is unique.

\>CanonicalPcgs( <pcgs> ) A

returns the canonical pcgs corresponding to the induced pcgs <pcgs>.


\beginexample
gap> G := Group((1,2,3,4),(5,6,7));
Group([ (1,2,3,4), (5,6,7) ])
gap> P := Pcgs(G);
Pcgs([ (5,6,7), (1,2,3,4), (1,3)(2,4) ])
gap> I := InducedPcgsByPcSequence(P, [(5,6,7)*(1,3)(2,4),(1,3)(2,4)] );
Pcgs([ (1,3)(2,4)(5,6,7), (1,3)(2,4) ])
gap> CanonicalPcgs(I);
Pcgs([ (5,6,7), (1,3)(2,4) ])
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Factor Groups of Polycyclic Groups - Modulo Pcgs}

Let <N> be a normal subgroup of <G> such that <G/N> is polycyclic
with pcgs $(h_1 N, \ldots, h_r N)$. Then we call the sequence of
preimages $(h_1, \ldots h_r)$ a *modulo pcgs* of <G/N>.
<G> is called the *numerator* of the modulo pcgs and <N> is the
*denominator* of the modulo pcgs.

Modulo pcgs are often used to facilitate efficient computations with
factor groups, since they allow computations with factor groups without
formally defining the factor group at all.

All elementary operations of pcgs, see Sections "Elementary Operations
for a Pcgs" and "Elementary Operations for a Pcgs and an Element",
apply to modulo pcgs as well. However, it is in general not possible to
compute induced pcgs with respect to a modulo pcgs.

\>ModuloPcgs( <G>, <N> ) O

returns a modulo pcgs for the factor $<G>/<N>$ which must be solvable,
which <N> may be insolvable.

`ModuloPcgs' will return *a* pcgs for the factor, there is no guarantee that
it will be ``compatible'' with any other pcgs. If this is required, the
`mod' operator must be used on induced pcgs, see below.

\>IsModuloPcgs( <obj> ) C

The category of modulo pcgs. Note that each pcgs is a modulo pcgs for
the trivial subgroup. 


Additionally there are two more elementary operations for modulo pcgs.

\>NumeratorOfModuloPcgs( <pcgs> ) A

returns a generating set for the numerator of the modulo pcgs <pcgs>.

\>DenominatorOfModuloPcgs( <pcgs> ) A

returns a generating set for the denominator of the modulo pcgs <pcgs>. 


\beginexample
gap> G := Group( (1,2,3,4,5),(1,2) );
Group([ (1,2,3,4,5), (1,2) ])
gap> P := ModuloPcgs(G, DerivedSubgroup(G) );
Pcgs([ (4,5) ])
gap> NumeratorOfModuloPcgs(P);
[ (1,2,3,4,5), (1,2) ]
gap> DenominatorOfModuloPcgs(P);
[ (1,3,2), (2,4,3), (2,3)(4,5) ]
gap> RelativeOrders(P);
[ 2 ]
gap> ExponentsOfPcElement( P, (1,2,3,4,5) );
[ 0 ]
gap> ExponentsOfPcElement( P, (4,5) );
[ 1 ]
\endexample

Modulo Pcgs can also be built from compatible induced pcgs.
Let <G> be a group with pcgs <P> and let <I> be an induced pcgs of
a normal subgroup <N> of <G>. (Respectively: <P> and <I> are both induced
with respect to the *same* Pcgs.) Then we can compute a modulo pcgs of
<G> mod <N> by

\>`<P> mod <I>'{modulo!for pcgs}

Note that in this case we obtain the advantage that the
`NumeratorOfModuloPcgs' and the `DenominatorOfModuloPcgs' are
just <P> and <I>, respectively, and hence are unique.

The resulting modulo pcgs will consist of a subset of <P> and will be
``compatible'' with <P> (or its parent).

\beginexample
gap> G := Group((1,2,3,4));;
gap> P := Pcgs(G);
Pcgs([ (1,2,3,4), (1,3)(2,4) ])
gap> I := InducedPcgsByGenerators(P, [(1,3)(2,4)]);
Pcgs([ (1,3)(2,4) ])
gap> M := P mod I;
[ (1,2,3,4) ]
gap> NumeratorOfModuloPcgs(M);
Pcgs([ (1,2,3,4), (1,3)(2,4) ])
gap> DenominatorOfModuloPcgs(M);
Pcgs([ (1,3)(2,4) ])
\endexample

\>CorrespondingGeneratorsByModuloPcgs( <mpcgs>, <imgs> ) O

let <mpcgs> be a modulo pcgs for a factor of a group $G$ and let
$U$ be a subgroup of $G$ generated by <imgs> such that $U$
covers the factor for the modulo pcgs. Then this function computes
elements in $U$ corresponding to the generators of the modulo pcgs.

Note that the computation of induced generating sets is not possible
for some modulo pcgs.

\>CanonicalPcgsByGeneratorsWithImages( <pcgs>, <gens>, <imgs> ) O

computes a canonical, <pcgs>-induced pcgs for the span of <gens> and
simultaneously does the same transformations on <imgs>, preserving thus
a correspondence between <gens> and <imgs>. This operation is used to
represent homomorphisms from a pc group.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Factor Groups of Polycyclic Groups in their Own Representation}

If substantial calculations are done in a factor it might be worth still to
construct the factor group in its own representation (for example by
calling `PcGroupWithPcgs' on a modulo pcgs, see~"PcGroupWithPcgs").

The following functions are intended for working with factor groups
obtained by factoring out the tail of a pcgs.
They provide a way to map elements or induced pcgs quickly in the factor
(respectively to take preimages) without the need to construct a
homomorphism.

The setup is always a pcgs <pcgs> of <G> and a pcgs <fpcgs> of a factor
group $<H>=<G>/<N>$ which corresponds to a head of <pcgs>.

No tests for validity of the input are performed.


\>ProjectedPcElement( <pcgs>, <fpcgs>, <elm> ) F

returns the image in <H> of an element <elm> of <G>.

\>ProjectedInducedPcgs( <pcgs>, <fpcgs>, <ipcgs> ) F

<ipcgs> must be an induced pcgs with respect to <pcgs>. This operation
returns an induced pcgs with respect to <fpcgs> consisting of the
nontrivial images of <ipcgs>.

\>LiftedPcElement( <pcgs>, <fpcgs>, <elm> ) F

returns a preimage in <G> of an element <elm> of <H>.

\>LiftedInducedPcgs( <pcgs>, <fpcgs>, <ipcgs>, <ker> ) F

<ipcgs> must be an induced pcgs with respect to <fpcgs>. This operation
returns an induced pcgs with respect to <pcgs> consisting of the
preimages of <ipcgs>, appended by the elements in <ker> (assuming
there is a bijection of <pcgs> mod <ker> to <fpcgs>). <ker> might be a
simple element list.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Pcgs and Normal Series}

By definition, a pcgs determines a pc series of its underlying group.
However, in many applications it will be necessary that this pc series
refines a normal series with certain properties; for example, a normal
series with abelian factors.

There are functions in {\GAP} to compute a pcgs through a normal series
with elementary abelian factors, a central series or the lower p-central
series. See also Section "Special Pcgs" for a more explicit possibility.

\>IsPcgsElementaryAbelianSeries( <pcgs> ) P

returns `true' if the pcgs <pcgs> refines an elementary abelian series.
`IndicesEANormalSteps' then gives the indices in the Pcgs, at which the
subgroups of this series start. 

\>PcgsElementaryAbelianSeries( <G> ) A
\>PcgsElementaryAbelianSeries( [<G>, <N1>, <N2>, ....] ) A

computes a pcgs for <G> that refines an elementary abelian series.
`IndicesEANormalSteps' gives the indices in the Pcgs, at which the
normal subgroups of this series start.  The second variant returns a
pcgs that runs through the normal subgroups <N1>, <N2>, etc.

\>IndicesEANormalSteps( <pcgs> ) A

Let <pcgs> be a pcgs obtained as corresponding to a series of normal
subgroups with elementary abelian factors (for example from calling
`PcgsElementaryAbelianSeries')
Then `IndicesEANormalSteps' returns a sorted list of
integers, indicating the tails of <pcgs> which generate these normal
subgroup of <G>. If $i$ is an element of this list, $(g_i, \ldots, g_n)$
is a normal subgroup of <G>.  The list always starts with 1 and ends
with n+1. (These indices form *one* series with elementary abelian
subfactors, not necessarily the most refined one.)

The attribute `EANormalSeriesByPcgs' returns the actual series of
subgroups.

For arbitrary pcgs not obtained as belonging to a special series such a
set of indices not necessarily exists, and `IndicesEANormalSteps' is not
guaranteed to work in this situation.

Typically, `IndicesEANormalSteps' is set by
`PcgsElementaryAbelianSeries'.

\>EANormalSeriesByPcgs( <pcgs> ) A

Let <pcgs> be a pcgs obtained as corresponding to a series of normal
subgroups with elementary abelian factors (for example from calling
`PcgsElementaryAbelianSeries'). This attribute returns the actual series
of normal subgroups, corresponding to `IndicesEANormalSteps'.


\>IsPcgsCentralSeries( <pcgs> ) P

returns `true' if the pcgs <pcgs> refines an central elementary abelian
series.  `IndicesCentralNormalSteps' then gives the indices in the Pcgs,
at which the subgroups of this series start. 

\>PcgsCentralSeries( <G> ) A

computes a pcgs for <G> that refines a central elementary abelian series.
`IndicesCentralNormalSteps' gives the indices in the Pcgs, at which the
normal subgroups of this series start.

\>IndicesCentralNormalSteps( <pcgs> ) A

Let <pcgs> be a pcgs obtained as corresponding to a series of normal
subgroups with central elementary abelian factors (for example from calling
`PcgsCentralSeries')
Then `IndicesCentralNormalSteps' returns a sorted list of
integers, indicating the tails of <pcgs> which generate these normal
subgroup of <G>. If $i$ is an element of this list, $(g_i, \ldots, g_n)$
is a normal subgroup of <G>.  The list always starts with 1 and ends
with n+1. (These indices form *one* series with central elementary abelian
subfactors, not necessarily the most refined one.)

The attribute `CentralNormalSeriesByPcgs' returns the actual series of
subgroups.

For arbitrary pcgs not obtained as belonging to a special series such a
set of indices not necessarily exists, and `IndicesCentralNormalSteps'
is not guaranteed to work in this situation.

Typically, `IndicesCentralNormalSteps' is set by
`PcgsCentralSeries'.

\>CentralNormalSeriesByPcgs( <pcgs> ) A

Let <pcgs> be a pcgs obtained as corresponding to a series of normal
subgroups with central elementary abelian factors (for example from
calling `PcgsCentralSeries'). This attribute returns the actual series
of normal subgroups, corresponding to `IndicesCentralNormalSteps'.


\>IsPcgsPCentralSeriesPGroup( <pcgs> ) P

returns `true' if the pcgs <pcgs> refines an $p$-central elementary
abelian series for a $p$-group.  `IndicesPCentralNormalStepsPGroup' then
gives the indices in the Pcgs, at which the subgroups of this series
start. 

\>PcgsPCentralSeriesPGroup( <G> ) A

computes a pcgs for the $p$-group <G> that refines a $p$-central
elementary abelian series.  `IndicesPCentralNormalStepsPGroup' gives the
indices in the Pcgs, at which the normal subgroups of this series start.

\>IndicesPCentralNormalStepsPGroup( <pcgs> ) A

Let <pcgs> be a pcgs obtained as corresponding to a series of normal
subgroups with $p$-central elementary abelian factors (for example from
calling `PcgsPCentralSeriesPGroup').
Then `IndicesPCentralNormalStepsPGroup' returns a sorted list of
integers, indicating the tails of <pcgs> which generate these normal
subgroup of <G>. If $i$ is an element of this list, $(g_i, \ldots, g_n)$
is a normal subgroup of <G>.  The list always starts with 1 and ends
with n+1. (These indices form *one* series with central elementary abelian
subfactors, not necessarily the most refined one.)

The attribute `PCentralNormalSeriesByPcgsPGroup' returns the actual
series of subgroups.

For arbitrary pcgs not obtained as belonging to a special series such a
set of indices not necessarily exists, and
`IndicesPCentralNormalStepsPGroup'
is not guaranteed to work in this situation.

Typically, `IndicesPCentralNormalStepsPGroup' is set by
`PcgsPCentralSeriesPGroup'.

\>PCentralNormalSeriesByPcgsPGroup( <pcgs> ) A

Let <pcgs> be a pcgs obtained as corresponding to a series of normal
subgroups with $p$-central elementary abelian factors (for example from
calling `PcgsPCentralSeriesPGroup'). This attribute returns the actual
series of normal subgroups, corresponding to
`IndicesPCentralNormalStepsPGroup'.


\>IsPcgsChiefSeries( <pcgs> ) P

returns `true' if the pcgs <pcgs> refines a chief series.
`IndicesChiefNormalSteps' then gives the indices in the Pcgs, at which the
subgroups of this series start. 

\>PcgsChiefSeries( <G> ) A

computes a pcgs for <G> that refines a chief series.
`IndicesChiefNormalSteps' gives the indices in the Pcgs, at which the
normal subgroups of this series start.

\>IndicesChiefNormalSteps( <pcgs> ) A

Let <pcgs> be a pcgs obtained as corresponding to a chief series
for example from calling `PcgsChiefSeries').
Then `IndicesChiefNormalSteps' returns a sorted list of
integers, indicating the tails of <pcgs> which generate these normal
subgroup of <G>. If $i$ is an element of this list, $(g_i, \ldots, g_n)$
is a normal subgroup of <G>.  The list always starts with 1 and ends
with n+1. (These indices form *one* series with elementary abelian
subfactors, not necessarily the most refined one.)

The attribute `ChiefNormalSeriesByPcgs' returns the actual series of
subgroups.

For arbitrary pcgs not obtained as belonging to a special series such a
set of indices not necessarily exists, and `IndicesChiefNormalSteps' is not
guaranteed to work in this situation.

Typically, `IndicesChiefNormalSteps' is set by
`PcgsChiefSeries'.

\>ChiefNormalSeriesByPcgs( <pcgs> ) A

Let <pcgs> be a pcgs obtained as corresponding to a chief series
(for example from calling
`PcgsChiefSeries'). This attribute returns the actual series
of normal subgroups, corresponding to `IndicesChiefNormalSteps'.


\beginexample
gap> g:=Group((1,2,3,4),(1,2));;
gap> p:=PcgsElementaryAbelianSeries(g);
Pcgs([ (3,4), (2,4,3), (1,4)(2,3), (1,3)(2,4) ])
gap> IndicesEANormalSteps(p);
[ 1, 2, 3, 5 ]
gap> g:=Group((1,2,3,4),(1,5)(2,6)(3,7)(4,8));;
gap> p:=PcgsCentralSeries(g);
Pcgs([ (1,5)(2,6)(3,7)(4,8), (5,6,7,8), (5,7)(6,8), (1,4,3,2)(5,6,7,8), 
  (1,3)(2,4)(5,7)(6,8) ])
gap> IndicesCentralNormalSteps(p);
[ 1, 2, 4, 5, 6 ]
gap> q:=PcgsPCentralSeriesPGroup(g);
Pcgs([ (1,5)(2,6)(3,7)(4,8), (5,6,7,8), (5,7)(6,8), (1,4,3,2)(5,6,7,8), 
  (1,3)(2,4)(5,7)(6,8) ])
gap> IndicesPCentralNormalStepsPGroup(q);
[ 1, 3, 5, 6 ]
\endexample

\>IndicesNormalSteps( <pcgs> ) A


returns the indices of *all* steps in the pc series, which are normal in
the group defined by the pcgs.

(In general, this function yields a slower performance than the more
specialized index functions for elementary abelian series etc.)

\>NormalSeriesByPcgs( <pcgs> ) A

returns the subgroups the pc series, which are normal in
the group defined by the pcgs.

(In general, this function yields a slower performance than the more
specialized index functions for elementary abelian series etc.)


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Sum and Intersection of Pcgs}

%eclaration{SumPcgs}
%eclaration{IntersectionSumPcgs}
%eclaration{NormalIntersectionPcgs}
\>SumFactorizationFunctionPcgs( <parentpcgs>, <n>, <u>, <kerpcgs> ) O

computes the sum and intersection of the lists <n> and <u> whose
elements form modulo pcgs induced by <parentpcgs> for two subgroups
modulo a kernel given by <kerpcgs>.
If <kerpcgs> is a tail if the <parent-pcgs> it is sufficient to give the
starting depth, this can be more efficient than to construct an explicit
pcgs.
The factor group modulo <kerpcgs> generated by <n> must be elementary
abelian and normal under <u>.

The function returns a record with components
\beginitems
`sum'&Elements that form a modulo pcgs for the span of both subgroups.

`intersection'&Elements that form a modulo pcgs for the intersection of
both subgroups.

`factorization'&A function that returns for an element <x> in the span
of `sum' a record with components `u' and `n' that give its
decomposition.
\enditems
The record components `sum' and `intersection' are *not* pcgs but only
lists of pc elements (to avoid unnecessary creation of InducedPcgs).


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Special Pcgs}

In short, a special pcgs is a pcgs which has particularly nice properties,
for example it always refines an elementary abelian series, for $p$-groups
it even refines a central series. These nice properties permit particularly
efficient algorithms.

Let <G> be a finite polycyclic group. A *special pcgs* of <G> is a pcgs
which is closely related to a Hall system and the maximal subgroups of <G>.
These pcgs have been introduced by C. R. Leedham-Green who also gave an
algorithm to compute them. Improvements to this algorithm
%%  and the {\GAP} implementation
are due to Bettina Eick.  For a more detailed account of
their definition the reader is referred to \cite{Eick97}

To introduce the definition of special pcgs we first need to define
the *LG-series* and *head complements* of a finite polycyclic group <G>.
Let $G = G_1 > G_2 > \ldots G_m > G_{m+1} = \{1\}$ be the lower
nilpotent series of $G$; that is, $G_i$ is the smallest normal
subgroup of $G_{i-1}$ with nilpotent factor. To obtain the LG-series
of <G> we need to refine this series. Thus consider a factor $F_i :=
G_i / G_{i+1}$. Since $F_i$ is finite nilpotent, it is a direct
product of its Sylow subgroups, say $F_i = P_{i,1} \cdots P_{i,r_i}$.
For each Sylow $p_j$-subgroup $P_{i, j}$ we can consider its
lower $p_j$-central series. To obtain a characteristic central series
with elementary abelian factors of $F_i$ we loop over its Sylow subgroups.
Each time we consider $P_{i,j}$ in this process we take the next step of
its lower $p_j$-central series into the series of $F_i$. If there
is no next step, then we just skip the consideration of $P_{i,j}$.
Note that the second term of the lower $p$-central series of a $p$-group
is in fact its Frattini subgroup. Thus the Frattini subgroup of $F_i$
is contained in the computed series of this group. We denote the
Frattini subgroup of $F_i = G_i / G_{i+1}$ by $G_i^{*} / G_{i+1}$.

The factors $G_i / G_i^{*}$ are called the heads of $G$, while the
(possibly trivial) factors $G_i^{*} / G_{i+1}$ are the tails of $G$.
A head complement of $G$ is a subgroup $U$ of $G$ such that $U / G_i^{*}$
is a complement to the head $G_i / G_i^{*}$ in $G / G_i^{*}$ for some $i$.

Now we are able to define a special pcgs of <G>. It is a pcgs of <G>
with three additional properties. First, the pc series determined
by the pcgs refines the LG-series of <G>. Second, a special pcgs
*exhibits* a Hall system of the group <G>; that is, for each set of
primes $\pi$ the elements of the pcgs with relative order in $\pi$
form a pcgs of a Hall $\pi$-subgroup in a Hall system of <G>.
Third, a special pcgs exhibits a head complement for each head
of <G>.

To record information about the LG-series with the special pcgs
we define the *LGWeights* of the special pcgs. These weights are
a list which contains a weight $w$ for each elements $g$ of the
special pcgs. Such a weight $w$ represents the smallest subgroup of
the LG-series containing $g$.

Since the LG-series is defined in terms of the lower nilpotent
series, Sylow subgroups of the factors and lower
$p$-central series of the Sylow subgroup, the weight $w$ is a
triple. More precisely, $g$ is contained in the $w[1]$th term
$U$ of the lower nilpotent series of <G>, but not in the next smaller
one $V$. Then $w[3]$ is a prime such that $g V$ is contained in the
Sylow $w[3]$-subgroup $P/V$ of $U/V$. Moreover, $gV$ is contained in
the $w[2]$th term of the lower $p$-central series of $P/V$.

There are two more attributes of a special pcgs containing
information about the LG-series: the list *LGLayers* and the
list *LGFirst*. The list of layers corresponds to the elements
of the special pcgs and denotes the layer of the LG-series in
which an element lies. The list LGFirst corresponds to the
LG-series and gives the number of the first element in the
special pcgs of the corresponding subgroup.

\>IsSpecialPcgs( <obj> ) P

tests whether <obj> is a special pcgs.

\>SpecialPcgs( <pcgs> )!{attribute} A
\>SpecialPcgs( <G> )!{attribute} A

computes a special pcgs for the group defined by <pcgs> or for <G>.

\>LGWeights( <pcgs> ) A

returns the LGWeights of the special pcgs <pcgs>.

\>LGLayers( <pcgs> ) A

returns the layers of the special pcgs <pcgs>.

\>LGFirst( <pcgs> ) A

returns the first indices for each layer of the special pcgs <pcgs>.

\>LGLength( <G> ) A

returns the Length of the LG-series of the group <G>, if <G> is  solvable
and <fail> otherwise.


\beginexample
gap> G := SmallGroup( 96, 220 );
<pc group of size 96 with 6 generators>
gap> spec := SpecialPcgs( G );
Pcgs([ f1, f2, f3, f4, f5, f6 ])
gap> LGWeights(spec);
[ [ 1, 1, 2 ], [ 1, 1, 2 ], [ 1, 1, 2 ], [ 1, 1, 2 ], [ 1, 1, 3 ], 
  [ 1, 2, 2 ] ]
gap> LGLayers(spec);
[ 1, 1, 1, 1, 2, 3 ]
gap> LGFirst(spec);
[ 1, 5, 6, 7 ]
gap> LGLength( G );
3
\endexample

\beginexample
gap> p := SpecialPcgs( Pcgs( SmallGroup( 96, 120 ) ) );
Pcgs([ f1, f2, f3, f4, f5, f6 ])
gap> LGWeights(p);
[ [ 1, 1, 2 ], [ 1, 1, 2 ], [ 1, 1, 2 ], [ 1, 2, 2 ], [ 1, 3, 2 ], 
  [ 2, 1, 3 ] ]
\endexample

Thus the first group, `SmallGroup(96, 220)', has a lower nilpotent series of
length 1; that is, the group is nilpotent. It is a direct product
of its Sylow subgroups. Moreover the Sylow 2-subgroup is generated by
$f1, f2, f3, f4, f6$ and the Sylow 3-subgroup is generated by $f5$.
The lower 2-central series of the Sylow 2-subgroup has length 2
and the second subgroup in this series is generated by $f6$.

The second group, `SmallGroup(96, 120)', has a lower nilpotent series of length
2 and hence is not nilpotent. The second subgroup in this series
is just the Sylow 3-subgroup and it is generated by $f6$. The subgroup
generated by $f1, \ldots, f5$ is a Sylow 2-subgroup of the group and
also a head complement to the second head of the group. Its lower
2-central series has length 2.

In this example the `FamilyPcgs' of the groups used was a special pcgs, but
this is not necessarily the case. For performance reasons it can be worth to
enforce this, see~"IsomorphismSpecialPcGroup".

\>IsInducedPcgsWrtSpecialPcgs( <pcgs> ) P

tests whether <pcgs> is induced with respect to a special pcgs.

\>InducedPcgsWrtSpecialPcgs( <G> ) A

computes an induced pcgs with respect to the special pcgs of the
parent of <G>.


`InducedPcgsWrtSpecialPcgs' will return a pcgs induced by *a* special pcgs
(which might differ from the one you had in mind).
If you need an induced pcgs compatible with a *given* special pcgs use
`InducedPcgs' for this special pcgs.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Action on Subfactors Defined by a Pcgs}

When working with a polycyclic group, one often needs to compute matrix
operations of the group on a factor of the group. For this purpose there
are the following functions.

\>VectorSpaceByPcgsOfElementaryAbelianGroup( <mpcgs>, <fld> ) F

returns the vector space over <fld> corresponding to the modulo pcgs
<mpcgs>. Note that <mpcgs> has to define an elementary abelian $p$-group
where $p$ is the characteristic of <fld>.

\>LinearOperation( <gens>, <basisvectors>, <linear> ) O
\>LinearAction( <gens>, <basisvectors>, <linear> ) O

returns a list of matrices, one for each element of <gens>, which
corresponds to the matrix action of the elements in <gens> on the
basis <basisvectors> via <linear>.

\>LinearOperationLayer( <G>, <gens>, <pcgs> ) F
\>LinearActionLayer( <G>, <gens>, <pcgs> ) F

returns a list of matrices, one for each element of <gens>, which
corresponds to the matrix action of <G> on the vector space corresponding
to the modulo pcgs <pcgs>.


In certain situations, for example within the computation of conjugacy
classes of finite soluble groups as described in \cite{MeckyNeubueser89},
affine actions of groups are required. For this purpose we introduce
the following functions.

\>AffineOperation( <gens>, <basisvectors>, <linear>, <transl> ) O
\>AffineAction( <gens>, <basisvectors>, <linear>, <transl> ) O

return a list of matrices, one for each element of <gens>, which
corresponds to the affine action of the elements in <gens> on the
basis <basisvectors> via <linear> with translation <transl>.

\>AffineOperationLayer( <G>, <gens>, <pcgs>, <transl> ) F
\>AffineActionLayer( <G>, <gens>, <pcgs>, <transl> ) F

returns a list of matrices, one for each element of <gens>, which
corresponds to the affine action of <G> on the vector space corresponding
to the modulo pcgs <pcgs> with translation <transl>.


\beginexample
gap> G := SmallGroup( 96, 51 );
<pc group of size 96 with 6 generators>
gap> spec := SpecialPcgs( G );
Pcgs([ f1, f2, f3, f4, f5, f6 ])
gap> LGWeights( spec );
[ [ 1, 1, 2 ], [ 1, 1, 2 ], [ 1, 1, 3 ], [ 1, 2, 2 ], [ 1, 2, 2 ], 
  [ 1, 3, 2 ] ]
gap> mpcgs := InducedPcgsByPcSequence( spec, spec{[4,5,6]} );
Pcgs([ f4, f5, f6 ])
gap> npcgs := InducedPcgsByPcSequence( spec, spec{[6]} );
Pcgs([ f6 ])
gap> modu := mpcgs mod npcgs;
[ f4, f5 ]
gap> mat:=LinearActionLayer( G, spec{[1,2,3]}, modu );
[ <an immutable 2x2 matrix over GF2>, <an immutable 2x2 matrix over GF2>, 
  <an immutable 2x2 matrix over GF2> ]
gap> Print( mat, "\n" );
[ [ [ Z(2)^0, 0*Z(2) ], [ 0*Z(2), Z(2)^0 ] ], 
  [ [ Z(2)^0, 0*Z(2) ], [ 0*Z(2), Z(2)^0 ] ], 
  [ [ Z(2)^0, 0*Z(2) ], [ 0*Z(2), Z(2)^0 ] ] ]
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Orbit Stabilizer Methods for Polycyclic Groups}

If a pcgs <pcgs> is known for a group <G>, then orbits and stabilizers
can be computed by a special method which is particularly efficient.
Note that within this function only the elements in <pcgs> and the
relative orders of <pcgs> are needed. Hence this function works effectively
even if the elementary operations for <pcgs> are slow.

\> StabilizerPcgs( <pcgs>, <pt> )

\>Pcgs_OrbitStabilizer( <pcgs>, <domain>, <pnt>, <oprs>, <opr> ) F

runs a solvable group orbit-stabilizer algorithm on <pnt> with <pcgs>
acting via the images <oprs> and the operation function <opr>.
The domain <domain> can be used to speed up search, if it is not known,
`false' can be given instead.
The function
returns a record with components `orbit', `stabpcgs' and `lengths', the
latter indicating the lengths of the orbit whenever it got extended.
This can be used to recompute transversal elements.
This function should be used only inside algorithms when speed is
essential.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Operations which have Special Methods for Groups with Pcgs}

\indextt{IsNilpotent!for groups with pcgs}
\indextt{IsSupersolvable!for groups with pcgs}
\indextt{Size!for groups with pcgs}
\indextt{CompositionSeries!for groups with pcgs}
\indextt{ConjugacyClasses!for groups with pcgs}
\indextt{Centralizer!for groups with pcgs}
\indextt{FrattiniSubgroup!for groups with pcgs}
\indextt{PrefrattiniSubgroup!for groups with pcgs}
\indextt{MaximalSubgroups!for groups with pcgs}
\indextt{HallSystem!for groups with pcgs}
\indextt{MinimalGeneratingSet!for groups with pcgs}
\indextt{Centre!for groups with pcgs}
\indextt{Intersection!for groups with pcgs}
\indextt{AutomorphismGroup!for groups with pcgs}
\indextt{IrreducibleModules!for groups with pcgs}
For the following methods there are special operations for groups with
pcgs installed:

`IsNilpotent', `IsSupersolvable', `Size', `CompositionSeries', 
`ConjugacyClasses', `Centralizer', `FrattiniSubgroup', `PrefrattiniSubgroup',
`MaximalSubgroups' and related operations, `HallSystem' and related operations,
`MinimalGeneratingSet', `Centre', `Intersection', `AutomorphismGroup', 
`IrreducibleModules'.

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

There are a variety of algorithms to compute conjugacy classes and
centralizers in solvable groups via epimorphic images
(\cite{FelschNeubueser79}, \cite{MeckyNeubueser89}, \cite{Theissen93}).
Usually these are only invoked as methods, but it is possible to access the
algorithm directly.

@*The syntax of this function may change in a future rewrite!*@

\>ClassesSolvableGroup( <G>, <mode> [, <opt>] ) F

computes conjugacy classes and centralizers in solvable groups. <G> is
the acting group. <mode> indicates the type of the calculation:

0 Conjugacy classes

4 Conjugacy test for the two elements in <opt>`.candidates'

In mode 0 the function returns a list of records containing components
<representative> and <centralizer>. In mode <4> it returns a
conjugating element.

The optional record <opt> may contain the following components that will
affect the algorithms behaviour:

\beginitems
`pcgs'&is a pcgs that will be used for the calculation.
The attribute `EANormalSeriesByPcgs' must return an
appropriate series of normal subgroups with elementary abelian factors
among them. The algorithm will step down this series.
In the case of
the calculation of rational classes, it must be a pcgs refining a
central series.

`candidates'&is a list of elements for which canonical representatives
are to be computed or for which a conjugacy test is performed. They must
be given in mode 4. In mode 0 a list of classes corresponding to
<candidates> is returned (which may contain duplicates). The
<representative>s chosen are canonical with respect to <pcgs>. The
records returned also contain components <operator>
such that
(<candidate> `^' <operator>) =<representative>.

`consider'&is a function <consider>(<fhome>,<rep>,<cenp>,<K>,<L>). Here
<fhome> is a home pcgs for the factor group <F> in which the calculation
currently takes place, <rep> is an element of the factor and <cenp> is a
pcgs for the centralizer of <rep> modulo <K>. In mode 0, when lifting
from <F>/<K> to <F>/<L> (note: for efficiency reasons, <F> can be
different from <G> or <L> might be not trivial) this function is called
before performing the actual lifting and only those representatives for
which it returns `true' are passed to the next level. This permits for
example the calculation of only those classes with small centralizers or
classes of restricted orders.
\enditems

\>CentralizerSizeLimitConsiderFunction( <sz> ) F

returns a function  (of the form func(<fhome>,<rep>,<cen>,<K>,<L>)
)that can be used in `ClassesSolvableGroup' as the <consider> component
of the options record. It will restrict the lifting to those classes,
for which the size of the centralizer (in the factor) is at most <sz>.


See also `SubgroupsSolvableGroup' ("SubgroupsSolvableGroup").