%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  pcpmeths.tex           GAP documentation                 Bettina Eick
%W                                                          Werner Nickel
%%
%H  $Id: methods.tex,v 1.7 2003/10/29 14:26:26 werner Exp $
%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Chapter{Higher level methods for pcp-groups}

This is a description of some higher level functions of the {\sf polycyclic}
package of GAP 4. Throughout this chapter we let <G> be a pc-presented group 
and we consider algorithms for subgroups <U> and <V> of <G>. For background
and a description of the underlying algorithms we refer to \cite{Eic01b}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Subgroup series in pcp-groups}

Many  algorithm for  pcp-groups work  by induction  using  some series
through  the group.  In this  section we  provide a  number  of useful
series  for pcp-groups.   An  *efa  series* is  a  normal series  with
elementary or free abelian  factors.  See \cite{Eic00} for outlines on
the algorithms of a number of the available series.

\>PcpSeries( <U> )

returns the polycyclic series of <U> defined by an igs of <U>.

\>EfaSeries( <U> )

returns a normal series of <U> with elementary or free abelian factors.

\> SemiSimpleEfaSeries( <U> )

returns an efa series of <U> such that every factor in the series is
semisimple as a module for <U> over a finite field or over the rationals.

\>DerivedSeries( <U> )

the derived series of <U>.

\>RefinedDerivedSeries( <U> )

the  derived series of <U> refined  to an efa series such that
in each abelian factor of the  derived series the free abelian
factor is at the top.

\>RefinedDerivedSeriesDown( <U> )

the  derived series of <U> refined  to an efa series such that
in each abelian factor of  the derived series the free abelian
factor is at the bottom.

\>LowerCentralSeries( <U> )

the lower  central  series of <U>.  If  <U>  does not   have a
largest  nilpotent quotient group, then  this function may not
terminate.

\> UpperCentralSeries( <U> )

the upper central series of <U>. This function always terminates,
but it may terminate at a proper subgroup of <U>. 

\>TorsionByPolyEFSeries( <U> )

returns  an  efa series  of   <U> such  that  all torsion-free
factors  are  at the  top and  all  finite  factors are at the
bottom. Such a series might not exist for <U> and in this case
the function returns fail.

\beginexample
gap> G := ExamplesOfSomePcpGroups(5);
Pcp-group with orders [ 2, 0, 0, 0 ]
gap> Igs(G);
[ g1, g2, g3, g4 ]

gap> PcpSeries(G);
[ Pcp-group with orders [ 2, 0, 0, 0 ],
  Pcp-group with orders [ 0, 0, 0 ],
  Pcp-group with orders [ 0, 0 ],
  Pcp-group with orders [ 0 ],
  Pcp-group with orders [  ] ]

gap> List( PcpSeries(G), Igs );
[ [ g1, g2, g3, g4 ], [ g2, g3, g4 ], [ g3, g4 ], [ g4 ], [  ] ]
\endexample

Algorithms for pcp-groups often use an efa series of $G$ and work down
over the factors of  this series. Usually,   pcp's of the factors  are
more useful than the actual factors. Hence we provide the following.

\>PcpsBySeries( <ser> )
\>PcpsBySeries( <ser>, <"snf"> )

returns  a  list of  pcp's corresponding  to  the factors of the
series.   If   the second argument  is  present,  then  each pcp
corresponds to a decomposition of  the abelian groups into direct
factors.

\>PcpsOfEfaSeries( <U> )

returns a list of pcps corresponding to an efa series of <U>.

\beginexample
gap> G := ExamplesOfSomePcpGroups(5);
Pcp-group with orders [ 2, 0, 0, 0 ]

gap> PcpsBySeries( DerivedSeries(G));
[ Pcp [ g1, g2, g3, g4 ] with orders [ 2, 2, 2, 2 ],
  Pcp [ g2^-2, g3^-2, g4^2 ] with orders [ 0, 0, 4 ],
  Pcp [ g4^8 ] with orders [ 0 ] ]
gap> PcpsBySeries( RefinedDerivedSeries(G));
[ Pcp [ g1, g2, g3 ] with orders [ 2, 2, 2 ],
  Pcp [ g4 ] with orders [ 2 ],
  Pcp [ g2^2, g3^2 ] with orders [ 0, 0 ],
  Pcp [ g4^2 ] with orders [ 2 ],
  Pcp [ g4^4 ] with orders [ 2 ],
  Pcp [ g4^8 ] with orders [ 0 ] ]

gap> PcpsBySeries( DerivedSeries(G), "snf" );
[ Pcp [ g2, g3, g1 ] with orders [ 2, 2, 4 ], 
  Pcp [ g4^2, g3^-2, g2^2*g4^2 ] with orders [ 4, 0, 0 ], 
  Pcp [ g4^8 ] with orders [ 0 ] ]
gap> G.1^4 in DerivedSubgroup( G );
true
gap> G.1^2 = G.4;                          
true

gap>  PcpsOfEfaSeries( G );
[ Pcp [ g1 ] with orders [ 2 ],
  Pcp [ g2 ] with orders [ 0 ],
  Pcp [ g3 ] with orders [ 0 ],
  Pcp [ g4 ] with orders [ 0 ] ]
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Orbit stabilizer methods for pcp-groups}

Let <U> be a pcp-group which acts on a set $\Omega$. One of the fundamental
problems in algorithmic group theory is the determination of orbits and 
stabilizers of points in $\Omega$ under the action of <U>. We distinguish
two cases: the case that all considered orbits are finite and the case that
there are infinite orbits. In the latter case, an orbit cannot be listed 
and a description of the orbit and its corresponding stabilizer is much 
harder to obtain.

If the considered orbits are finite, then the following two functions can be
applied to compute the considered orbits and their corresponding stabilizers.

\> PcpOrbitStabilizer( <point>, <gens>, <acts>, <oper> ) 
\> PcpOrbitsStabilizers( <points>, <gens>, <acts>, <oper> )

The input <gens> can be an igs or a pcp of a pcp-group <U>. The elements
in the list <gens> act as the elements in the list <acts> via the function
<oper> on the given points; that is, <oper( point, acts[i] )> applies the
$i$th generator to a given point. Thus the group defined by <acts> must be
a homomorphic image of the group defined by <gens>. The first function 
returns a record containing the orbit as component 'orbit' and and igs for 
the stabilizer as component 'stab'. The second function returns a list of 
records, each record contains 'repr' and 'stab'. Both of these functions 
run forever on infinite orbits.

\beginexample
gap> G := DihedralPcpGroup( 0 );
Pcp-group with orders [ 2, 0 ]
gap> mats := [ [[-1,0],[0,1]], [[1,1],[0,1]] ];;
gap> pcp := Pcp(G);
Pcp [ g1, g2 ] with orders [ 2, 0 ]
gap> PcpOrbitStabilizer( [0,1], pcp, mats, OnRight );
rec( orbit := [ [ 0, 1 ] ],
     stab := [ g1, g2 ],
     word := [ [ [ 1, 1 ] ], [ [ 2, 1 ] ] ] )
\endexample

If the considered orbits are infinite, then it may not always be possible
to determine a description of the orbits and their stabilizers. However, 
as shown in \cite{EOs01} and \cite{Eic02}, it is possible to determine 
stabilizers and check if two elements are contained in the same orbit if 
the given action of the polycyclic group is a unimodular linear action on
a vector space. The following functions are available for this case.

\> StabilizerIntegralAction( <U>, <mats>, <v> )
\> OrbitIntegralAction( <U>, <mats> , <v>, <w> )

The first function computes the stabilizer in <U> of the vector <v> where
the pcp group <U> acts via <mats> on an integral space and <v> and <w> are 
elements in this integral space. The second function checks whether <v> and 
<w> are in the same orbit and the function returns either <false> or a 
record containing an element in <U> mapping <v> to <w> and the stabilizer 
of <v>. 

\> NormalizerIntegralAction( <U>, <mats>, <B> )
\> ConjugacyIntegralAction( <U>, <mats>, <B>, <C> )

The first function computes the normalizer in <U> of the lattice with the
basis <B>, where the pcp group <U> acts via <mats> on an integral space and
<B> is a subspace of this integral space. The second functions checks whether
the two lattices with the bases <B> and <C> are contained in the same orbit 
under <U>. The function returns either <false> or a record with an element 
in <U> mapping <B> to <C> and the stabilizer of <B>.

\beginexample
# get a pcp group and a free abelian normal subgroup
gap> G := ExamplesOfSomePcpGroups(8);
Pcp-group with orders [ 0, 0, 0, 0, 0 ]
gap> efa := EfaSeries(G);
[ Pcp-group with orders [ 0, 0, 0, 0, 0 ],
  Pcp-group with orders [ 0, 0, 0, 0 ], 
  Pcp-group with orders [ 0, 0, 0 ],
  Pcp-group with orders [  ] ]
gap> N := efa[3];
Pcp-group with orders [ 0, 0, 0 ]
gap> IsFreeAbelian(N);
true

# create conjugation action on N
gap> mats := LinearActionOnPcp(Igs(G), Pcp(N));
[ [ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ],
  [ [ 0, 0, 1 ], [ 1, -1, 1 ], [ 0, 1, 0 ] ],
  [ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ],
  [ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ],
  [ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ] ]

# take an arbitrary vector and compute its stabilizer
gap> StabilizerIntegralAction(G,mats, [2,3,4]);
Pcp-group with orders [ 0, 0, 0, 0 ]
gap> Igs(last);
[ g1, g3, g4, g5 ]

# check orbits with some other vectors
gap> OrbitIntegralAction(G,mats, [2,3,4],[3,1,5]);
rec( stab := Pcp-group with orders [ 0, 0, 0, 0 ], prei := g2 )

gap> OrbitIntegralAction(G,mats, [2,3,4], [4,6,8]);
false

# compute the orbit of a subgroup of Z^3 under the action of G
gap> NormalizerIntegralAction(G, mats, [[1,0,0],[0,1,0]]);
Pcp-group with orders [ 0, 0, 0, 0, 0 ]
gap> Igs(last);
[ g1, g2^2, g3, g4, g5 ]
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Centralizers, Normalizers and Intersections}

In this section we list a number of operations for which there are methods
installed to compute the corresponding features in polycyclic groups. 

\> Centralizer( <U>, <g> )!{element in subgroup}
\> IsConjugate( <U>, <g>, <h> )!{elements}

These functions solve the conjugacy problem for elements in pcp-groups and 
they can be used to compute centralizers. The first method returns a 
subgroup of the given group <U>, the second method either returns a 
conjugating element or false if no such element exists.

The methods are based on the orbit stabilizer algorithms described in 
\cite{EOs01}. For nilpotent groups, an algorithm to solve the conjugacy
problem for elements is described in \cite{Sims94}. 

\> Centralizer( <U>, <V> )!{subgroup in subgroup}
\> Normalizer( <U>, <V> )
\> IsConjugate( <U>, <V>, <W> )!{subgroups}

These three functions solve the conjugacy problem for subgroups and compute 
centralizers and normalizers of subgroups. The first two functions return 
subgroups of the input group <U>, the third function returns a conjugating 
element or false if no such element exists.

The methods are based on the orbit stabilizer algorithms described in 
\cite{Eic02}. For nilpotent groups, an algorithm to solve the conjugacy
problems for subgroups is described in \cite{Lo98}.

\> Intersection( <U>, <N> )

A general method to compute intersections of subgroups of a pcp-group is 
described in \cite{Eic01b}, but it is not yet implemented here. However, 
intersections of subgroups $U, N \leq G$ can be computed if $N$ is 
normalising $U$. See \cite{Sims94} for an outline of the algorithm.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Finite subgroups}

There are various finite subgroups of interest in polycyclic groups. See
\cite{Eic00} for a description of the algorithms underlying the functions
in this section.

\> TorsionSubgroup( <U> )

If the set of elements of finite order forms a subgroup, then we call
it the *torsion subgroup*. This function determines the torsion subgroup
of <U>, if it exists, and returns fail otherwise. Note that a torsion
subgroup does always exist if <U> is nilpotent.

\> NormalTorsionSubgroup( <U> )

Each polycyclic groups has a unique largest finite normal subgroup.
This function computes it for <U>. 

\> IsTorsionFree( <U> )

This function checks if <U> is torsion free. It returns true or false.

\> FiniteSubgroupClasses( <U> )

There exist only finitely many conjugacy classes of finite subgroups
in a polycyclic group <U> and this function can be used to compute
them. The algorithm underlying this function proceeds by working down
a normal series of <U> with elementary or free abelian factors. The
following function can be used to give the algorithm a specific series.

\> FiniteSubgroupClassesBySeries( <U>, <pcps> )

\beginexample
gap> G := ExamplesOfSomePcpGroups(15);
Pcp-group with orders [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 5, 4, 0 ]
gap> TorsionSubgroup(G);
Pcp-group with orders [ 5, 2 ]
gap> NormalTorsionSubgroup(G);
Pcp-group with orders [ 5, 2 ]
gap> IsTorsionFree(G);
false
gap> FiniteSubgroupClasses(G);
[ Pcp-group with orders [ 5, 2 ]^G,
  Pcp-group with orders [ 2 ]^G,
  Pcp-group with orders [ 5 ]^G,
  Pcp-group with orders [  ]^G ]

gap> G := DihedralPcpGroup( 0 );
Pcp-group with orders [ 2, 0 ]
gap> TorsionSubgroup(G);
fail
gap> NormalTorsionSubgroup(G);
Pcp-group with orders [  ]
gap> IsTorsionFree(G);
false
gap> FiniteSubgroupClasses(G);
[ Pcp-group with orders [ 2 ]^G,
  Pcp-group with orders [ 2 ]^G,
  Pcp-group with orders [  ]^G ]
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Subgroups of finite index and maximal subgroups}

Here we outline functions to determine various types of subgroups of 
finite index in polycyclic groups. Again, see \cite{Eic00} for a 
description of the algorithms underlying the functions in this section.
Also, we refer to \cite{Lo99} for an alternative appraoch.

\> MaximalSubgroupClassesByIndex( <U>, <p> )

Each maximal subgroup of a polycyclic group <U> has <p>-power index for
some prime <p>. This function can be used to determine the conjugacy 
classes of all maximal subgroups of <p>-power index for a given prime <p>.

\>LowIndexSubgroupClasses( <U>, <n> )

There are only finitely many subgroups of a given index in a polycyclic
group <U>. This function computes conjugacy classes of all subgroups of 
index <n> in <U>.

\>LowIndexNormals( <U>, <n> )

This function computes the normal subgroups of index <n> in <U>. 

\>NilpotentByAbelianNormalSubgroup( <U> )

This function returns a normal subgroup <N> of finite index in <U> such 
that <N> is nilpotent-by-abelian. Such a subgroup exists in every polycyclic 
group and this function computes such a subgroup using LowIndexNormal. 
However, we note that this function is not very efficient and the function
NilpotentByAbelianByFiniteSeries may well be more efficient on this task.

\beginexample
gap> G := ExamplesOfSomePcpGroups(2);
Pcp-group with orders [ 0, 0, 0, 0, 0, 0 ]

gap> MaximalSubgroupClassesByIndex( G, 61 );;
gap> max := List( last, Representative );;
gap> List( max, x -> Index( G, x ) );
[ 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61,
  61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61,
  61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61,
  61, 61, 61, 61, 61, 61, 226981 ]

gap> LowIndexSubgroupClasses( G, 61 );;
gap> low := List( last, Representative );;
gap> List( low, x -> Index( G, x ) );
[ 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61,
  61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61,
  61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61, 61,
  61, 61, 61, 61, 61, 61 ]
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Further attributes for pcp-groups based on the Fitting subgroup}

In this section we provide a variety of other attributes for pcp-groups. Most
of the methods below are based or related to the Fitting subgroup of the given
group. We refer to \cite{Eic01} for a description of the underlying methods.  

\> FittingSubgroup( <U> )

returns the Fitting subgroup of <U>; that is, the largest nilpotent normal
subgroup of <U>.

\> IsNilpotentByFinite( <U> )

checks whether the Fitting subgroup of <U> has finite index. 

\> Centre( <U> )

returns the centre of <U>.

\> FCCentre( <U> )

returns the FC-centre of <U>; that is, the subgroup containing all elements
having a finite conjugacy class in <U>.

\> PolyZNormalSubgroup( <U> )

returns a normal subgroup <N> of <U> such that <N> has a polycyclic series
with infinite factors only.

\> NilpotentByAbelianByFiniteSeries( <U> )

returns a normal series $1 \leq F \leq A \leq U$ such that $F$ is nilpotent, 
$A/F$ is abelian and $U/A$ is finite. This series is computed using the
Fitting subgroup and the centre of the Fitting factor.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Functions for nilpotent groups}

There are (very few) functions which are available for nilpotent groups only.
First, there are the different central series. These are available for all
groups, but for nilpotent groups they terminate and provide series though
the full group. Secondly, the determination of a minimal generating set is
available for nilpotent groups only.

\>MinimalGeneratingSet( <U> )

\beginexample
gap> G := ExamplesOfSomePcpGroups(14);
Pcp-group with orders [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 5, 4, 0, 5, 5, 4, 0, 6,
  5, 5, 4, 0, 10, 6 ]
gap> IsNilpotent(G);
true

gap> PcpsBySeries( LowerCentralSeries(G));
[ Pcp [ g1, g2 ] with orders [ 0, 0 ],
  Pcp [ g3 ] with orders [ 0 ],
  Pcp [ g4 ] with orders [ 0 ],
  Pcp [ g5 ] with orders [ 0 ],
  Pcp [ g6, g7 ] with orders [ 0, 0 ],
  Pcp [ g8 ] with orders [ 0 ],
  Pcp [ g9, g10 ] with orders [ 0, 0 ],
  Pcp [ g11, g12, g13 ] with orders [ 5, 4, 0 ],
  Pcp [ g14, g15, g16, g17, g18 ] with orders [ 5, 5, 4, 0, 6 ],
  Pcp [ g19, g20, g21, g22, g23, g24 ] with orders [ 5, 5, 4, 0, 10, 6 ] ]

gap> PcpsBySeries( UpperCentralSeries(G));
[ Pcp [ g1, g2 ] with orders [ 0, 0 ],
  Pcp [ g3 ] with orders [ 0 ],
  Pcp [ g4 ] with orders [ 0 ],
  Pcp [ g5 ] with orders [ 0 ],
  Pcp [ g6, g7 ] with orders [ 0, 0 ],
  Pcp [ g8 ] with orders [ 0 ],
  Pcp [ g9, g10 ] with orders [ 0, 0 ],
  Pcp [ g11, g12, g13 ] with orders [ 5, 4, 0 ],
  Pcp [ g14, g15, g16, g17, g18 ] with orders [ 5, 5, 4, 0, 6 ],
  Pcp [ g19, g20, g21, g22, g23, g24 ] with orders [ 5, 5, 4, 0, 10, 6 ] ]

gap> MinimalGeneratingSet(G);
[ g1, g2 ]
\endexample


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Random methods for pcp-groups}

Below we introduce a function which computes orbit and stabilizer using 
a random method. This function tries to approximate the orbit and the 
stabilizer, but the returned orbit or stabilizer may be incomplete. 
This function is used in the random methods to compute normalizers and 
centralizers. Note that determinstic methods for these purposes are also
available.

\> RandomOrbitStabilizerPcpGroup( <U>, <point>, <oper> )

\> RandomCentralizerPcpGroup( <U>, <g> )
\> RandomCentralizerPcpGroup( <U>, <V> )

\> RandomNormalizerPcpGroup( <U>, <V> )

\beginexample
gap> G := DihedralPcpGroup(0);
Pcp-group with orders [ 2, 0 ]
gap> mats := [[[-1, 0],[0,1]], [[1,1],[0,1]]];
[ [ [ -1, 0 ], [ 0, 1 ] ], [ [ 1, 1 ], [ 0, 1 ] ] ]
gap> pcp := Pcp(G);
Pcp [ g1, g2 ] with orders [ 2, 0 ]

gap> RandomPcpOrbitStabilizer( [1,0], pcp, mats, OnRight ).stab;
#I  Orbit longer than limit: exiting.
[  ]

gap> g := Igs(G)[1];
g1
gap> RandomCentralizerPcpGroup( G, g );
#I  Stabilizer not increasing: exiting.
Pcp-group with orders [ 2 ]
gap> Igs(last);
[ g1 ]
\endexample

