%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  pcpmeths.tex           GAP documentation                 Bettina Eick
%W                                                          Werner Nickel
%%
%H  $Id: methods.tex,v 1.13 2009/02/18 10:46:02 gap 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

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Non-abelian tensor product and Schur extensions}

\>SchurExtension( <G> )

Let <G> be a polycyclic group with a polycyclic generating sequence
consisting of $n$ elements.  This function computes the largest
central extension <H> of  <G> such that <H> is generated by $n$
elements.  If $F/R$ is the underlying polycyclic presentation for <G>,
then <H> is isomorphic to $F/[R,F]$. 

\beginexample
gap> G := DihedralPcpGroup( 0 );
Pcp-group with orders [ 2, 0 ]
gap> Centre( G );
Pcp-group with orders [  ]
gap> H := SchurExtension( G );
Pcp-group with orders [ 2, 0, 0, 0 ]
gap> Centre( H );
Pcp-group with orders [ 0, 0 ]
gap> H/Centre(H);
Pcp-group with orders [ 2, 0 ]
gap> Subgroup( H, [H.1,H.2] ) = H;
true
\endexample

\>SchurExtensionEpimorphism( <G> )

returns the  projection from the  Schur extension $G^{*}$ of  <G> onto
<G>.   See   the  function  `SchurExtension'.   The   kernel  of  this
epimorphism is  the direct product  of the Schur multiplicator  of <G>
and a direct product of $n$ copies  of $\Z$ where $n$ is the number of
generators  in  the  polycyclic   presentation  for  <G>.   The  Schur
multiplicator is the intersection of  the kernel and the derived group
of the source.  See also the function `SchurCovering'.

\beginexample
gap> gl23 := Range( IsomorphismPcpGroup( GL(2,3) ) );
Pcp-group with orders [ 2, 3, 2, 2, 2 ]
gap> SchurExtensionEpimorphism( gl23 );
[ g1, g2, g3, g4, g5, g6, g7, g8, g9, g10 ] -> [ g1, g2, g3, g4, g5,
id, id, id, id, id ]
gap> Kernel( last );
Pcp-group with orders [ 0, 0, 0, 0, 0 ]
gap> SchurMultiplicator( gl23 );
[  ]
gap> Intersection( Kernel(epi), DerivedSubgroup( Source(epi) ) );
[  ]
\endexample

There  is a  crossed pairing  from <G>  into $(G^{*})'$  which  can be
defined via this epimorphism:

\beginexample
gap> G := DihedralPcpGroup(0);
Pcp-group with orders [ 2, 0 ]
gap> epi := SchurExtensionEpimorphism( G );
[ g1, g2, g3, g4 ] -> [ g1, g2, id, id ]
gap> PreImagesRepresentative( epi, G.1 );
g1
gap> PreImagesRepresentative( epi, G.2 );
g2
gap> Comm( last, last2 );
g2^-2*g4
\endexample

\>SchurCovering( <G> )

computes a Schur covering group  of the polycyclic group <G>.  A Schur
covering  is a  largest central  extension <H>  of <G>  such  that the
kernel  <M> of  the projection  of <H>  onto <G>  is contained  in the
commutator subgroup of <H>.

If <G> is given by a presentation $F/R$, then <M> is isomorphic to the
subgroup $R \cap [F,F] / [R,F]$.  Let $C$ be a complement to 
$R \cap [F,F] / [R,F]$ in $R/[R,F]$.  Then $F/C$ is isomorphic to <H>
and $R/C$ is isomorphic to <M>.

\beginexample
gap> G := AbelianPcpGroup( 3,[] );
Pcp-group with orders [ 0, 0, 0 ]
gap> ext := SchurCovering( G );
Pcp-group with orders [ 0, 0, 0, 0, 0, 0 ]
gap> Centre( ext );
Pcp-group with orders [ 0, 0, 0 ]
gap> IsSubgroup( DerivedSubgroup( ext ), last );
true
\endexample

\>SchurMultiplicator( <G> )

computes the  isomorphism type of  the Schur multiplicator of  <G> and
returns a  list of pairs describing  the isomorphism type  as a direct
product of cyclic groups.  The first  component of a pair is the order
of the  cyclic group.  The  second component specifies how  often that
cyclic group occurs  as a direct factor.  The  isomorphism type of the
Schur multiplicator is  the direct product of the  groups specified by
the list of pairs.

If  a cyclic  factor  is infinite,  then  the first  component of  the
corresponding  pair is  0.  

Note that the Schur multiplicator  of a polycyclic group is a fintiely
generated abelian group.
 
\beginexample
gap> G := DihedralPcpGroup( 0 );
Pcp-group with orders [ 2, 0 ]
gap> DirectProduct( G, AbelianPcpGroup( 2, [] ) );
Pcp-group with orders [ 0, 0, 2, 0 ]
gap> SchurMultiplicator( last );
[ [ 2, 4 ], [ 0, 1 ] ]
\endexample

\>NonAbelianExteriorSquareEpimorphism( <G> )

returns  the  epimorphism of  the  non-abelian  exterior  square of  a
polycylic group  <G> onto the  derived group of <G>.   The non-abelian
exterior  square can be  defined as  the derived  subgroup of  a Schur
cover of <G>.  The isomorphism type of the non-abelian exterior square
is unique despite the fact that  the isomorphism type of a Schur cover
of a  polycyclic groups need  not be unique.   The derived group  of a
Schur cover  has a  natural projection onto  the derived group  of <G>
which is what the function returns.

The kernel of the epimorphism is isomorphic to the Schur multiplicator
of <G>.

\beginexample
gap> G := ExamplesOfSomePcpGroups( 3 );
Pcp-group with orders [ 0, 0 ]
gap> G := DirectProduct( G,G );
Pcp-group with orders [ 0, 0, 0, 0 ]
gap> SchurMultiplicator( G );
[ [ 0, 1 ], [ 2, 3 ] ]
gap> epi := NonAbelianExteriorSquareEpimorphism( G );
[ g2^-2*g5, g4^-2*g10, g6, g7, g8, g9 ] -> [ g2^-2, g4^-2, id, id, id, id ]
gap> Kernel( epi );
Pcp-group with orders [ 0, 2, 2, 2 ]
gap> Collected( AbelianInvariants( last ) );
[ [ 0, 1 ], [ 2, 3 ] ]
\endexample

\>NonAbelianExteriorSquare( <G> )

computes the  non-abelian exterior  square of a  polycylic group  <G>. 
See  the explanation  for  `NonAbelianExteriorSquareEpimorphism'.  The
natural projection of the non-abelian exterior square onto the derived
group of <G> is stored in the component `!.epimorphism'.

There  is  a crossed  pairing  from <G>  into  $G\wedge  G$.  See  the
function `SchurExtensionEpimorphism' for details.  The crossed pairing
is stored  in the component  `!.crossedPairing'.  This is  the crossed
pairing $\lambda$ in \cite{EickNickel07}.

\beginexample
gap> G := DihedralPcpGroup(0);
Pcp-group with orders [ 2, 0 ]
gap> GwG := NonAbelianExteriorSquare( G );
Pcp-group with orders [ 0 ]
gap> lambda := GwG!.crossedPairing;
function( g, h ) ... end
gap> lambda( G.1, G.2 );
g2^2*g4^-1
\endexample

\>NonAbelianTensorSquareEpimorphism( <G> )

returns for a  polycyclic group <G> the projection  of the non-abelian
tensor  square  $G\otimes  G$  onto the  non-abelian  exterior  square
$G\wedge  G$.   The  range  of  that  epimorphism  has  the  component
`!.epimorphism'  set to  the  projection of  the non-abelian  exterior
square  onto  the  derived  group  of  <G>.   See  also  the  function
`NonAbelianExteriorSquare'.

With the  result of this  function one can  compute the groups  in the
commutative diagram at the beginning of the paper \cite{EickNickel07}.
The kernel of  the returned epimorphism is the  group $\nabla(G)$. The
kernel of  the composition of  this epimorphism and the  above mention
projection onto $G'$ is the group $J(G)$.

\beginexample
gap> G := DihedralPcpGroup(0);
Pcp-group with orders [ 2, 0 ]
gap> G := DirectProduct(G,G);
Pcp-group with orders [ 2, 0, 2, 0 ]
gap> alpha := NonAbelianTensorSquareEpimorphism( G );
[ g9*g25^-1, g10*g26^-1, g11*g27, g12*g28, g13*g29, g14*g30, g15, g16,
g17,
  g18, g19, g20, g21, g22, g23, g24 ] -> [ g2^-2*g6, g4^-2*g12, g8,
  g9, g10,
  g11, id, id, id, id, id, id, id, id, id, id ]
gap> gamma := Range( alpha )!.epimorphism;
[ g2^-2*g6, g4^-2*g12, g8, g9, g10, g11 ] -> [ g2^-2, g4^-2, id, id,
id, id ]
gap> JG := Kernel( alpha * gamma );
Pcp-group with orders [ 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2 ]
gap> Image( alpha, JG );
Pcp-group with orders [ 2, 2, 2, 2 ]
gap> SchurMultiplicator( G );
[ [ 2, 4 ] ]

\>NonAbelianTensorSquare( <G> )

computes  for a  polycyclic group  <G> the  non-abelian  tensor square
$G\otimes G$.

\beginexample
gap> G := AlternatingGroup( IsPcGroup, 4 );
<pc group of size 12 with 3 generators>
gap> PcGroupToPcpGroup( G );
Pcp-group with orders [ 3, 2, 2 ]
gap> NonAbelianTensorSquare( last );
Pcp-group with orders [ 2, 2, 2, 3 ]
gap> PcpGroupToPcGroup( last );
<pc group of size 24 with 4 generators>
gap> DirectFactorsOfGroup( last );
[ Group([ f1, f2, f3 ]), Group([ f4 ]) ]
gap> List( last, Size );
[ 8, 3 ]
gap> IdGroup( last2[1] );
[ 8, 4 ]       # the quaternion group of Order 8

gap> G := DihedralPcpGroup( 0 );
Pcp-group with orders [ 2, 0 ]
gap> ten := NonAbelianTensorSquare( G );
Pcp-group with orders [ 0, 2, 2, 2 ]
gap> IsAbelian( ten );
true
\endexample

\>NonAbelianExteriorSquarePlusEmbedding( <G> )

returns an embedding from  the non-abelian exterior square $G\wedge G$
into  an  extensions   of  $G\wedge  G$  by  $G\times   G$.   For  the
significance  of the  group  see the  paper \cite{EickNickel07}.   The
range of the epimorphism is the group $\tau(G)$ in that paper.

\>NonAbelianExteriorSquarePlusEmbedding( <G> )

returns the group $\tau(G)$ in \cite{EickNickel07}.

\>NonAbelianTensorSquarePlusEpimorphism( <G> )

returns  an  epimorphisms  of  $\nu(G)$  onto  $\tau(G)$.   The  group
$\nu(G)$ is an extension of the non-abelian tensor square $G\otimes G$
of $G$  by $G\times G$.   The group $\tau(G)$  is an extension  of the
non-abelian exterior  square $G\wedge G$ by $G\times  G$.  For details
see \cite{EickNickel07}.

\>NonAbelianTensorSquarePlus( <G> )

returns the group $\nu(G)$ in \cite{EickNickel07}.


\> WhiteheadQuadraticFunctor( <G> )

returns Whitehead's universal quadratic functor of $G$, see
\cite{EickNickel07} for a description.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Schur covers and Schur towers}

A finite $p$-group <G> is a Schur tower, if $G/\gamma_{i+1}(G)$ is a
Schur cover of $G/\gamma_i(G)$ for every $i$, where $\gamma_i(G)$ is
the $i$-th term of the lower central series of $G$. This section 
contains a function to determine the Schur covers of a finite $p$-group
up to isomorphism and it gives access to two libraries of Schur tower
$p$-groups.

\>SchurCovers( <G> )

Let <G> be a finite $p$-group defined as a pcp group. This function
returns a complete and irredundant set of isomorphism types of Schur
covers of <G>. The algorithm implements a method of Nickel's Phd Thesis.