<Chapter Label="Higher level methods for pcp-groups">
<Heading>Higher level methods for pcp-groups</Heading>

This is a description of some higher level functions of the &Polycyclic;
package of GAP 4. Throughout this chapter we let <A>G</A> be a pc-presented group
and we consider algorithms for subgroups <A>U</A> and <A>V</A> of <A>G</A>. For background
and a description of the underlying algorithms we refer to <Cite Key="Eic01b"/>.
<P/>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Subgroup series in pcp-groups">
<Heading>Subgroup series in pcp-groups</Heading>

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  <E>efa  series</E> is  a  normal series  with
elementary or free abelian  factors.  See <Cite Key="Eic00"/> for outlines on
the algorithms of a number of the available series.
<ManSection>
<Func Name="PcpSeries" Arg="U"/>
<Description>
	returns the polycyclic series of <A>U</A> defined by an igs of <A>U</A>.
</Description>
</ManSection>

<ManSection>
<Attr Name="EfaSeries" Arg="U"/>
<Description>
	returns a normal series of <A>U</A> with elementary or free abelian factors.
</Description>
</ManSection>

<ManSection>
<Attr Name="SemiSimpleEfaSeries" Arg="U"/>
<Description>
	returns an efa series of <A>U</A> such that every factor in the series is
	semisimple as a module for <A>U</A> over a finite field or over the rationals.
</Description>
</ManSection>

<ManSection>
<Meth Name="DerivedSeriesOfGroup" Arg="U"/>
<Description>
	the derived series of <A>U</A>.
</Description>
</ManSection>

<ManSection>
<Func Name="RefinedDerivedSeries" Arg="U"/>
<Description>
	the  derived series of <A>U</A> refined  to an efa series such that
	in each abelian factor of the  derived series the free abelian
	factor is at the top.
</Description>
</ManSection>

<ManSection>
<Func Name="RefinedDerivedSeriesDown" Arg="U"/>
<Description>
	the  derived series of <A>U</A> refined  to an efa series such that
	in each abelian factor of  the derived series the free abelian
	factor is at the bottom.
</Description>
</ManSection>

<ManSection>
<Meth Name="LowerCentralSeriesOfGroup" Arg="U"/>
<Description>
	the lower  central  series of <A>U</A>.  If  <A>U</A>  does not   have a
	largest  nilpotent quotient group, then  this function may not
	terminate.
</Description>
</ManSection>

<ManSection>
<Meth Name="UpperCentralSeriesOfGroup" Arg="U"/>
<Description>
	the upper central series of <A>U</A>. This function always terminates,
	but it may terminate at a proper subgroup of <A>U</A>.
</Description>
</ManSection>

<ManSection>
<Func Name="TorsionByPolyEFSeries" Arg="U"/>
<Description>
	returns  an  efa series  of   <A>U</A> 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 <A>U</A> and in this case
	the function returns fail.

<Example><![CDATA[
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 ], [  ] ]
]]></Example>
</Description>
</ManSection>

Algorithms for pcp-groups often use an efa series of <M>G</M> 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.

<ManSection>
<Func Name="PcpsBySeries" Arg="ser[, flag]"/>
<Description>
	returns a list of pcp's corresponding to the factors of the series. If
	the parameter <A>flag</A> is present and equals the string <Q>snf</Q>,
	then each pcp corresponds to a decomposition  of  the  abelian  groups
	into direct factors.
</Description>
</ManSection>

<ManSection>
<Attr Name="PcpsOfEfaSeries" Arg="U"/>
<Description>
	returns a list of pcps corresponding to an efa series of <A>U</A>.

<Example><![CDATA[
gap> G := ExamplesOfSomePcpGroups(5);
Pcp-group with orders [ 2, 0, 0, 0 ]

gap> PcpsBySeries( DerivedSeriesOfGroup(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( DerivedSeriesOfGroup(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 ] ]
]]></Example>
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Orbit stabilizer methods for pcp-groups">
<Heading>Orbit stabilizer methods for pcp-groups</Heading>

Let <A>U</A> be a pcp-group which acts on a set <M>\Omega</M>. One of the fundamental
problems in algorithmic group theory is the determination of orbits and
stabilizers of points in <M>\Omega</M> under the action of <A>U</A>. 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.
<P/>
If the considered orbits are finite, then the following two functions can be
applied to compute the considered orbits and their corresponding stabilizers.

<ManSection>
<Func Name="PcpOrbitStabilizer" Arg="point, gens, acts, oper"/>
<Func Name="PcpOrbitsStabilizers" Arg="points, gens, acts, oper"/>
<Description>
	The input <A>gens</A> can be an igs or a pcp of a pcp-group <A>U</A>. The elements
	in the list <A>gens</A> act as the elements in the list <A>acts</A> via the function
	<A>oper</A> on the given points; that is, <A>oper( point, acts[i] )</A> applies the
	<M>i</M>th generator to a given point. Thus the group defined by <A>acts</A> must be
	a homomorphic image of the group defined by <A>gens</A>. 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.

<Example><![CDATA[
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 ] ] ] )
]]></Example>
	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 Key="EOs01"/> and <Cite Key="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.
</Description>
</ManSection>

<ManSection>
<Func Name="StabilizerIntegralAction" Arg="U, mats, v"/>
<Func Name="OrbitIntegralAction" Arg="U, mats , v, w"/>
<Description>
	The first function computes the stabilizer in <A>U</A> of the vector <A>v</A> where
	the pcp group <A>U</A> acts via <A>mats</A> on an integral space and <A>v</A> and <A>w</A> are
	elements in this integral space. The second function checks whether <A>v</A> and
	<A>w</A> are in the same orbit and the function returns either <A>false</A> or a
	record containing an element in <A>U</A> mapping <A>v</A> to <A>w</A> and the stabilizer
	of <A>v</A>.
</Description>
</ManSection>

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

<Example><![CDATA[
# 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 ]
]]></Example>
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Centralizers, Normalizers and Intersections">
<Heading>Centralizers, Normalizers and Intersections</Heading>

In this section we list a number of operations for which there are methods
installed to compute the corresponding features in polycyclic groups.
<ManSection>
<Meth Name="Centralizer" Arg="U, g" Label="for an element"/>
<Meth Name="IsConjugate" Arg="U, g, h" Label="for elements"/>
<Description>
	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 <A>U</A>, the second method either returns a
	conjugating element or false if no such element exists.
	<P/>
	The methods are based on the orbit stabilizer algorithms described in
	<Cite Key="EOs01"/>. For nilpotent groups, an algorithm to solve the conjugacy
	problem for elements is described in <Cite Key="Sims94"/>.
</Description>
</ManSection>

<ManSection>
<Meth Name="Centralizer" Arg="U, V" Label="for a subgroup"/>
<Meth Name="Normalizer" Arg="U, V"/>
<Meth Name="IsConjugate" Arg="U, V, W" Label="for subgroups"/>
<Description>
	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 <A>U</A>, the third function returns a conjugating
	element or false if no such element exists.
	<P/>
	The methods are based on the orbit stabilizer algorithms described in
	<Cite Key="Eic02"/>. For nilpotent groups, an algorithm to solve the conjugacy
	problems for subgroups is described in <Cite Key="Lo98"/>.
</Description>
</ManSection>

<ManSection>
<Func Name="Intersection" Arg="U, N"/>
<Description>
	A general method to compute intersections of subgroups of a pcp-group is
	described in <Cite Key="Eic01b"/>, but it is not yet implemented here. However,
	intersections of subgroups <M>U, N \leq G</M> can be computed if <M>N</M> is
	normalising <M>U</M>. See <Cite Key="Sims94"/> for an outline of the algorithm.
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Finite subgroups">
<Heading>Finite subgroups</Heading>

There are various finite subgroups of interest in polycyclic groups. See
<Cite Key="Eic00"/> for a description of the algorithms underlying the functions
in this section.

<ManSection>
<Attr Name="TorsionSubgroup" Arg="U"/>
	<Description>
	If the set of elements of finite order forms a subgroup, then we call
	it the <E>torsion subgroup</E>. This function determines the torsion subgroup
	of <A>U</A>, if it exists, and returns fail otherwise. Note that a torsion
	subgroup does always exist if <A>U</A> is nilpotent.
</Description>
</ManSection>

<ManSection>
<Attr Name="NormalTorsionSubgroup" Arg="U"/>
<Description>
	Each polycyclic groups has a unique largest finite normal subgroup.
	This function computes it for <A>U</A>.
</Description>
</ManSection>

<ManSection>
<Prop Name="IsTorsionFree" Arg="U"/>
<Description>
	This function checks if <A>U</A> is torsion free. It returns true or false.
</Description>
</ManSection>

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

<ManSection>
<Func Name="FiniteSubgroupClassesBySeries" Arg="U, pcps"/>
<Description>
<Example><![CDATA[
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 ]
]]></Example>
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Subgroups of finite index and maximal subgroups">
<Heading>Subgroups of finite index and maximal subgroups</Heading>

Here we outline functions to determine various types of subgroups of
finite index in polycyclic groups. Again, see <Cite Key="Eic00"/> for a
description of the algorithms underlying the functions in this section.
Also, we refer to <Cite Key="Lo99"/> for an alternative approach.
<ManSection>
<Oper Name="MaximalSubgroupClassesByIndex" Arg="U, p"/>
<Description>
	Each maximal subgroup of a polycyclic group <A>U</A> has <A>p</A>-power index for
	some prime <A>p</A>. This function can be used to determine the conjugacy
	classes of all maximal subgroups of <A>p</A>-power index for a given prime <A>p</A>.
</Description>
</ManSection>

<ManSection>
<Oper Name="LowIndexSubgroupClasses" Arg="U, n"/>
<Description>
	There are only finitely many subgroups of a given index in a polycyclic
	group <A>U</A>. This function computes conjugacy classes of all subgroups of
	index <A>n</A> in <A>U</A>.
</Description>
</ManSection>

<ManSection>
<Oper Name="LowIndexNormalSubgroups" Arg="U, n"/>
<Description>
	This function computes the normal subgroups of index <A>n</A> in <A>U</A>.
</Description>
</ManSection>

<ManSection>
<Func Name="NilpotentByAbelianNormalSubgroup" Arg="U"/>
<Description>
	This function returns a normal subgroup <A>N</A> of finite index in <A>U</A> such
	that <A>N</A> 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.

<Example><![CDATA[
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 ]
]]></Example>
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Further attributes for pcp-groups based on the Fitting subgroup">
<Heading>Further attributes for pcp-groups based on the Fitting subgroup</Heading>

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 Key="Eic01"/> for a description of the underlying methods.
<ManSection>
<Attr Name="FittingSubgroup" Arg="U"/>
<Description>
	returns the Fitting subgroup of <A>U</A>; that is, the largest nilpotent normal
	subgroup of <A>U</A>.
</Description>
</ManSection>

<ManSection>
<Prop Name="IsNilpotentByFinite" Arg="U"/>
<Description>
	checks whether the Fitting subgroup of <A>U</A> has finite index.
</Description>
</ManSection>

<ManSection>
<Meth Name="Centre" Arg="U"/>
<Description>
	returns the centre of <A>U</A>.
</Description>
</ManSection>

<ManSection>
<Meth Name="FCCentre" Arg="U"/>
<Description>
	returns the FC-centre of <A>U</A>; that is, the subgroup containing all elements
	having a finite conjugacy class in <A>U</A>.
</Description>
</ManSection>

<ManSection>
<Func Name="PolyZNormalSubgroup" Arg="U"/>
<Description>
	returns a normal subgroup <A>N</A> of finite index in <A>U</A>, such that <A>N</A> has a
	polycyclic series with infinite factors only.
</Description>
</ManSection>

<ManSection>
<Func Name="NilpotentByAbelianByFiniteSeries" Arg="U"/>
<Description>
	returns a normal series <M>1 \leq F \leq A \leq U</M> such that <M>F</M> is nilpotent,
	<M>A/F</M> is abelian and <M>U/A</M> is finite. This series is computed using the
	Fitting subgroup and the centre of the Fitting factor.
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Functions for nilpotent groups">
<Heading>Functions for nilpotent groups</Heading>

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 through
the full group. Secondly, the determination of a minimal generating set is
available for nilpotent groups only.

<ManSection>
<Meth Name="MinimalGeneratingSet" Arg="U"/>
<Description>
<Example><![CDATA[
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( LowerCentralSeriesOfGroup(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( UpperCentralSeriesOfGroup(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 ]
]]></Example>
</Description>
</ManSection>


</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Random methods for pcp-groups">
<Heading>Random methods for pcp-groups</Heading>

<!-- % TODO: The following text talks about orbits and stabilizers, -->
<!-- % but the functions that follow only deal with centralizers and -->
<!-- % normalizers. -->
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 deterministic methods for these purposes are also
available.
<P/>
<!-- % TODO: The following operation does not actually exist: -->
<!-- %\> RandomOrbitStabilizerPcpGroup( <A>U</A>, <A>point</A>, <A>oper</A> ) -->
<!-- % If desired, it could be (re?)added, using the internal -->
<!-- % function RandomPcpOrbitStabilizer -->
<ManSection>
<Func Name="RandomCentralizerPcpGroup" Arg="U, g" Label="for an element"/>
<Func Name="RandomCentralizerPcpGroup" Arg="U, V" Label="for a subgroup"/>
<Func Name="RandomNormalizerPcpGroup" Arg="U, V"/>
<Description>
<Example><![CDATA[
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 ]
]]></Example>
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Non-abelian tensor product and Schur extensions">
<Heading>Non-abelian tensor product and Schur extensions</Heading>

<ManSection>
<Attr Name="SchurExtension" Arg="G"/>
<Description>
	Let <A>G</A> be a polycyclic group with a polycyclic generating sequence
	consisting of <M>n</M> elements.  This function computes the largest
	central extension <A>H</A> of  <A>G</A> such that <A>H</A> is generated by <M>n</M>
	elements.  If <M>F/R</M> is the underlying polycyclic presentation for <A>G</A>,
	then <A>H</A> is isomorphic to <M>F/[R,F]</M>.

<Example><![CDATA[
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
]]></Example>
</Description>
</ManSection>

<ManSection>
<Attr Name="SchurExtensionEpimorphism" Arg="G"/>
<Description>
	returns the  projection from the  Schur extension <M>G^{*}</M> of  <A>G</A> onto
	<A>G</A>.   See   the  function  <C>SchurExtension</C>.   The   kernel  of  this
	epimorphism is  the direct product  of the Schur multiplicator  of <A>G</A>
	and a direct product of <M>n</M> copies  of <M>&ZZ;</M> where <M>n</M> is the number of
	generators  in  the  polycyclic   presentation  for  <A>G</A>.   The  Schur
	multiplicator is the intersection of  the kernel and the derived group
	of the source.  See also the function <C>SchurCover</C>.

<Example><![CDATA[
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> AbelianInvariantsMultiplier( gl23 );
[  ]
gap> Intersection( Kernel(epi), DerivedSubgroup( Source(epi) ) );
[  ]
]]></Example>

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

<Example><![CDATA[
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
]]></Example>
</Description>
</ManSection>

<ManSection>
<Func Name="SchurCover" Arg="G"/>
<Description>
	computes a Schur covering group  of the polycyclic group <A>G</A>.  A Schur
	covering  is a  largest central  extension <A>H</A>  of <A>G</A>  such  that the
	kernel  <A>M</A> of  the projection  of <A>H</A>  onto <A>G</A>  is contained  in the
	commutator subgroup of <A>H</A>.
	<P/>

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

<Example><![CDATA[
gap> G := AbelianPcpGroup( 3 );
Pcp-group with orders [ 0, 0, 0 ]
gap> ext := SchurCover( 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
]]></Example>
</Description>
</ManSection>

<ManSection>
<Attr Name="AbelianInvariantsMultiplier" Arg="G"/>
<Description>
	returns a list of the abelian invariants of the Schur multiplier of G.
	<P/>

	Note that the Schur multiplicator  of a polycyclic group is a finitely
	generated abelian group.

<Example><![CDATA[
gap> G := DihedralPcpGroup( 0 );
Pcp-group with orders [ 2, 0 ]
gap> DirectProduct( G, AbelianPcpGroup( 2 ) );
Pcp-group with orders [ 0, 0, 2, 0 ]
gap> AbelianInvariantsMultiplier( last );
[ 0, 2, 2, 2, 2 ]
]]></Example>
</Description>
</ManSection>

<ManSection>
<Func Name="NonAbelianExteriorSquareEpimorphism" Arg="G"/>
<Description>
	returns  the  epimorphism of  the  non-abelian  exterior  square of  a
	polycyclic group  <A>G</A> onto the  derived group of <A>G</A>.   The non-abelian
	exterior  square can be  defined as  the derived  subgroup of  a Schur
	cover of <A>G</A>.  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 <A>G</A>
	which is what the function returns.
	<P/>

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

<Example><![CDATA[
gap> G := ExamplesOfSomePcpGroups( 3 );
Pcp-group with orders [ 0, 0 ]
gap> G := DirectProduct( G,G );
Pcp-group with orders [ 0, 0, 0, 0 ]
gap> AbelianInvariantsMultiplier( 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 ] ]
]]></Example>
</Description>
</ManSection>

<ManSection>
<Attr Name="NonAbelianExteriorSquare" Arg="G"/>
<Description>
	computes the  non-abelian exterior  square of a  polycyclic group  <A>G</A>.
	See  the explanation  for  <C>NonAbelianExteriorSquareEpimorphism</C>.  The
	natural projection of the non-abelian exterior square onto the derived
	group of <A>G</A> is stored in the component <C>!.epimorphism</C>.
	<P/>

	There  is  a crossed  pairing  from <M>G\times  G</M> into  <M>G\wedge  G</M>.  See  the
	function <C>SchurExtensionEpimorphism</C> for details.  The crossed pairing
	is stored  in the component  <C>!.crossedPairing</C>.  This is  the crossed
	pairing <M>\lambda</M> in <Cite Key="EickNickel07"/>.

<Example><![CDATA[
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
]]></Example>
</Description>
</ManSection>

<ManSection>
<Func Name="NonAbelianTensorSquareEpimorphism" Arg="G"/>
<Description>
	returns for a  polycyclic group <A>G</A> the projection  of the non-abelian
	tensor  square  <M>G\otimes  G</M>  onto the  non-abelian  exterior  square
	<M>G\wedge  G</M>.   The  range  of  that  epimorphism  has  the  component
	<C>!.epimorphism</C>  set to  the  projection of  the non-abelian  exterior
	square  onto  the  derived  group  of  <A>G</A>.   See  also  the  function
	<C>NonAbelianExteriorSquare</C>.
	<P/>

	With the  result of this  function one can  compute the groups  in the
	commutative diagram at the beginning of the paper <Cite Key="EickNickel07"/>.
	The kernel of  the returned epimorphism is the  group <M>\nabla(G)</M>. The
	kernel of  the composition of  this epimorphism and the  above mention
	projection onto <M>G'</M> is the group <M>J(G)</M>.

<Example><![CDATA[
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> AbelianInvariantsMultiplier( G );
[ [ 2, 4 ] ]
]]></Example>
</Description>
</ManSection>


<ManSection>
<Attr Name="NonAbelianTensorSquare" Arg="G"/>
<Description>
	computes  for a  polycyclic group  <A>G</A> the  non-abelian  tensor square
	<M>G\otimes G</M>.

<Example><![CDATA[
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
]]></Example>
</Description>
</ManSection>

<ManSection>
<Func Name="NonAbelianExteriorSquarePlusEmbedding" Arg="G"/>
<Description>
	returns an embedding from  the non-abelian exterior square <M>G\wedge G</M>
	into  an  extensions   of  <M>G\wedge  G</M>  by  <M>G\times   G</M>.   For  the
	significance  of the  group  see the  paper <Cite Key="EickNickel07"/>.   The
	range of the epimorphism is the group <M>\tau(G)</M> in that paper.
</Description>
</ManSection>

<ManSection>
<Func Name="NonAbelianTensorSquarePlusEpimorphism" Arg="G"/>
<Description>
	returns  an  epimorphisms  of  <M>\nu(G)</M>  onto  <M>\tau(G)</M>.   The  group
	<M>\nu(G)</M> is an extension of the non-abelian tensor square <M>G\otimes G</M>
	of <M>G</M>  by <M>G\times G</M>.   The group <M>\tau(G)</M>  is an extension  of the
	non-abelian exterior  square <M>G\wedge G</M> by <M>G\times  G</M>.  For details
	see <Cite Key="EickNickel07"/>.
</Description>
</ManSection>

<ManSection>
<Func Name="NonAbelianTensorSquarePlus" Arg="G"/>
<Description>
	returns the group <M>\nu(G)</M> in <Cite Key="EickNickel07"/>.
</Description>
</ManSection>

<ManSection>
<Func Name="WhiteheadQuadraticFunctor" Arg="G"/>
<Description>
	returns Whitehead's universal quadratic functor of <M>G</M>, see
	<Cite Key="EickNickel07"/> for a description.
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Schur covers">
<Heading>Schur covers</Heading>

This section contains a function to determine the Schur covers of a finite
<M>p</M>-group up to isomorphism.

<ManSection>
<Func Name="SchurCovers" Arg="G"/>
<Description>
	Let <A>G</A> be a finite <M>p</M>-group defined as a pcp group. This function
	returns a complete and irredundant set of isomorphism types of Schur
	covers of <A>G</A>. The algorithm implements a method of Nickel's Phd Thesis.
</Description>
</ManSection>

</Section>
</Chapter>