<Chapter Label="Basic methods and functions for pcp-groups">
<Heading>Basic methods and functions for pcp-groups</Heading>

Pcp-groups are groups in the &GAP; sense and hence all generic &GAP;
methods for groups can be applied for pcp-groups.  However, for a
number of group theoretic questions &GAP; does not provide generic
methods that can be applied to pcp-groups. For some of these questions
there are functions provided in &Polycyclic;.

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

In this chapter we describe some important basic functions which are
available for pcp-groups. A number of higher level functions are outlined
in later sections and chapters.
<P/>

Let <M>U, V</M> and <M>N</M> be subgroups of a pcp-group.

<ManSection>
<Meth Name="\=" Arg='U, V'/><!-- FIXME: Was:   \>`U = V'{equality}!{subgroups} O   -->
<Description>
	decides if <A>U</A> and <A>V</A> are equal as sets.
</Description>
</ManSection>

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

<ManSection>
<Meth Name="Random" Arg="U"/>
<Description>
	returns a random element of <A>U</A>.
</Description>
</ManSection>

<ManSection>
<Meth Name="Index" Arg="U, V"/>
<Description>
	returns the index of  <A>V</A> in <A>U</A>  if <A>V</A>  is  a subgroup of  <A>U</A>.  The
	function does not check if <A>V</A> is a subgroup of <A>U</A> and  if it is not,
	the result is not meaningful.
</Description>
</ManSection>

<ManSection>
<Meth Name="\in" Arg="g, U"/>
<Description>
	checks if <A>g</A> is an element of <A>U</A>.
</Description>
</ManSection>

<ManSection>
<Meth Name="Elements" Arg="U"/>
<Description>
	returns a list  containing all elements of  <A>U</A> if <A>U</A> is finite and it
	returns the list [fail] otherwise.
</Description>
</ManSection>

<ManSection>
<Meth Name="ClosureGroup" Arg="U, V"/>
<Description>
	returns the group generated by <A>U</A> and <A>V</A>.
</Description>
</ManSection>

<ManSection>
<Meth Name="NormalClosure" Arg="U, V"/>
<Description>
	returns  the normal closure of <A>V</A>  under action of <A>U</A>.
</Description>
</ManSection>

<ManSection>
<Meth Name="HirschLength" Arg="U"/>
<Description>
	returns the Hirsch length of <A>U</A>.
</Description>
</ManSection>

<ManSection>
<Meth Name="CommutatorSubgroup" Arg="U, V"/>
<Description>
	returns the group generated by all commutators <M>[u,v]</M> with <M>u</M> in <A>U</A>
and <M>v</M> in <A>V</A>.
</Description>
</ManSection>

<ManSection>
<Meth Name="PRump" Arg="U, p"/>
<Description>
	returns the subgroup <M>U'U^p</M> of <A>U</A> where <A>p</A> is a prime number.
</Description>
</ManSection>

<ManSection>
<Meth Name="SmallGeneratingSet" Arg="U"/>
<Description>
	returns a small generating set for <A>U</A>.
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Elementary properties of pcp-groups">
<Heading>Elementary properties of pcp-groups</Heading>

<ManSection>
<Func Name="IsSubgroup" Arg="U, V"/>
<Description>
	tests if <A>V</A> is a subgroup of <A>U</A>.
</Description>
</ManSection>

<ManSection>
<Func Name="IsNormal" Arg="U, V"/>
<Description>
	tests if <A>V</A> is normal in <A>U</A>.
</Description>
</ManSection>

<ManSection>
<Meth Name="IsNilpotentGroup" Arg="U"/>
<Description>
	checks whether <A>U</A> is nilpotent.
</Description>
</ManSection>

<ManSection>
<Meth Name="IsAbelian" Arg="U"/>
<Description>
	checks whether <A>U</A> is abelian.
</Description>
</ManSection>

<ManSection>
<Meth Name="IsElementaryAbelian" Arg="U"/>
<Description>
	checks whether <A>U</A> is elementary abelian.
</Description>
</ManSection>

<ManSection>
<Prop Name="IsFreeAbelian" Arg="U"/>
<Description>
	checks whether <A>U</A> is free abelian.
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Subgroups of pcp-groups">
<Heading>Subgroups of pcp-groups</Heading>

A subgroup of a pcp-group <M>G</M> can be defined by a set of generators as
described in Section <Ref Sect="pcpgroup"/>. However, many computations  with a
subgroup <M>U</M> need  an <E>induced generating sequence</E> or <E>igs</E>  of <M>U</M>.
An igs is a sequence of generators of <M>U</M> whose list of exponent vectors
form a matrix  in upper triangular form.  Note that there may  exist
many igs of <M>U</M>.  The first one  calculated for <M>U</M> is stored as an
attribute.
<P/>

An induced generating sequence of a subgroup of a pcp-group <M>G</M> is a
list of elements of <M>G</M>.  An igs is called <E>normed</E>, if each element
in the list is normed.  Moreover, it is <E>canonical</E>, if the exponent
vector matrix is in Hermite Normal Form. The following functions can
be used to compute induced generating sequence for a given subgroup
<A>U</A> of <A>G</A>.

<ManSection>
<Attr Name="Igs" Arg="U"/>
<Func Name="Igs" Arg="gens"/>
<Func Name="IgsParallel" Arg="gens, gens2"/>
<Description>
	returns an induced generating sequence of the subgroup <A>U</A> of a
	pcp-group. In the second form the subgroup is given via a generating
	set <A>gens</A>. The third form computes an igs for the subgroup generated
	by <A>gens</A> carrying <A>gens2</A> through as shadows.  This means that each
	operation that is applied to the first list is also applied to the
	second list.
</Description>
</ManSection>

<ManSection>
<Attr Name="Ngs" Arg="U"/>
<Func Name="Ngs" Arg="igs"/>
<Description>
	returns a normed induced generating sequence of the subgroup <A>U</A> of a
	pcp-group. The second form takes an igs as input and norms it.
</Description>
</ManSection>

<ManSection>
<Attr Name="Cgs" Arg="U"/>
<Func Name="Cgs" Arg="igs"/>
<Func Name="CgsParallel" Arg="gens, gens2"/>
<Description>
	returns a canonical generating sequence of the subgroup <A>U</A> of a
	pcp-group. In the second form the function takes an igs as input and
	returns a canonical generating sequence. The third version takes a
	generating set and computes a canonical generating sequence carrying
	<A>gens2</A> through as shadows.  This means that each operation that is
	applied to the first list is also applied to the second list.
	<P/>

	For a large number of methods for pcp-groups <A>U</A> we will first of all
	determine an <A>igs</A> for <A>U</A>. Hence it might speed up computations, if
	a known <A>igs</A> for a group <A>U</A> is set <E>a priori</E>. The following
	functions can be used for this purpose.
</Description>
</ManSection>

<ManSection>
<Func Name="SubgroupByIgs" Arg="G, igs"/>
<Func Name="SubgroupByIgs" Arg="G, igs, gens"/>
<Description>
	returns the subgroup of the pcp-group <A>G</A> generated by the elements of
	the induced  generating sequence <A>igs</A>.   Note that  <A>igs</A> must  be an
	induced generating sequence of  the subgroup generated by the elements
	of the <A>igs</A>. In the second form <A>igs</A> is a igs for a subgroup and
	<A>gens</A> are some generators. The function returns the subgroup generated
	by <A>igs</A> and <A>gens</A>.
</Description>
</ManSection>

<ManSection>
<Func Name="AddToIgs" Arg="igs, gens"/>
<Func Name="AddToIgsParallel" Arg="igs, gens, igs2, gens2"/>
<Func Name="AddIgsToIgs" Arg="igs, igs2"/>
<Description>
	sifts the elements in the list <M>gens</M> into <M>igs</M>.  The second version
	has the same functionality and carries shadows.  This means that each
	operation that is applied to the first list and the element <A>gens</A> is
	also applied to the second list and the element <A>gens2</A>.  The third
	version is available for efficiency reasons and assumes that the
	second list <A>igs2</A> is not only a generating set, but an igs.
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="pcps">
<Heading>Polycyclic presentation sequences for subfactors</Heading>

A subfactor of a pcp-group <M>G</M> is again a polycyclic group for which a
polycyclic presentation can be computed. However, to compute a polycyclic
presentation for  a given subfactor  can  be time-consuming.  Hence we
introduce <E>polycyclic presentation sequences</E> or <E>Pcp</E> to compute more
efficiently with subfactors. (Note that a subgroup is also a subfactor
and  thus can be handled by a pcp)
<P/>

A pcp for a pcp-group <M>U</M> or a subfactor <M>U /  N</M> can be created with
one of the following functions.

<ManSection>
<Func Name="Pcp" Arg="U[, flag]"/>
<Func Name="Pcp" Arg="U, N[, flag]"/>
<Description>
	returns a polycyclic presentation sequence for the subgroup <A>U</A> or the
	quotient group  <A>U</A> modulo <A>N</A>.  If the  parameter <A>flag</A> is present
	and equals the string <Q>snf</Q>,
	the function can only be applied to an abelian  subgroup <A>U</A>  or abelian
	subfactor   <A>U</A>/<A>N</A>.   The pcp  returned  will correspond     to a
	decomposition of  the abelian  group  into a direct  product of cyclic
	groups.
</Description>
</ManSection>


A  pcp   is  a component  object which    behaves similar  to   a list
representing an igs of the  subfactor in question. The basic functions
to   obtain  the  stored  values of  this     component object  are as
follows.  Let <M>pcp</M>  be a pcp  for  a subfactor <M>U/N</M>  of the defining
pcp-group <M>G</M>.


<ManSection>
<Func Name="GeneratorsOfPcp" Arg="pcp"/>
<Description>
	this returns a list   of elements of <M>U</M>   corresponding to an  igs of
	<M>U/N</M>.
</Description>
</ManSection>

<ManSection>
<Meth Name="\[\]" Arg="pcp, i"/> <!-- <Func Name="<C>pcp[i]</C>{pcp}!{as list}"/> FIXME -->
<Description>
	returns the <A>i</A>-th element of <A>pcp</A>.
</Description>
</ManSection>

<ManSection>
<Meth Name="Length" Arg="pcp"/>
<Description>
	returns the number of generators in <A>pcp</A>.
</Description>
</ManSection>

<ManSection>
<Func Name="RelativeOrdersOfPcp" Arg="pcp"/>
<Description>
	the relative orders of the igs in <A>U/N</A>.
</Description>
</ManSection>

<ManSection>
<Func Name="DenominatorOfPcp" Arg="pcp"/>
<Description>
	returns an igs of <A>N</A>.
</Description>
</ManSection>

<ManSection>
<Func Name="NumeratorOfPcp" Arg="pcp"/>
<Description>
	returns an igs of <A>U</A>.
</Description>
</ManSection>

<ManSection>
<Func Name="GroupOfPcp" Arg="pcp"/>
<Description>
	returns <A>U</A>.
</Description>
</ManSection>

<ManSection>
<Func Name="OneOfPcp" Arg="pcp"/>
<Description>
	returns the identity element of <A>G</A>.
</Description>
</ManSection>


The main feature of a pcp are the  possibility to compute exponent
vectors without having to determine an explicit pcp-group corresponding
to the subfactor that is represented by the pcp. Nonetheless, it is
possible to determine this subfactor.


<ManSection>
<Func Name="ExponentsByPcp" Arg="pcp, g"/>
<Description>
	returns the exponent vector  of <A>g</A> with  respect to the generators of
	<A>pcp</A>.  This is the exponent vector of <A>g</A><M>N</M> with  respect to the igs
	of <A>U/N</A>.
</Description>
</ManSection>

<ManSection>
<Func Name="PcpGroupByPcp" Arg="pcp"/>
<Description>
	let <A>pcp</A> be a Pcp of a subgroup or a factor group of a pcp-group. This
	function computes a new pcp-group whose defining generators correspond
	to the generators in <A>pcp</A>.

<Example><![CDATA[
gap>  G := DihedralPcpGroup(0);
Pcp-group with orders [ 2, 0 ]
gap>  pcp := Pcp(G);
Pcp [ g1, g2 ] with orders [ 2, 0 ]
gap>  pcp[1];
g1
gap>  Length(pcp);
2
gap>  RelativeOrdersOfPcp(pcp);
[ 2, 0 ]
gap>  DenominatorOfPcp(pcp);
[  ]
gap>  NumeratorOfPcp(pcp);
[ g1, g2 ]
gap>  GroupOfPcp(pcp);
Pcp-group with orders [ 2, 0 ]
gap> OneOfPcp(pcp);
identity
]]></Example>

<Example><![CDATA[
gap> G := ExamplesOfSomePcpGroups(5);
Pcp-group with orders [ 2, 0, 0, 0 ]
gap> D := DerivedSubgroup( G );
Pcp-group with orders [ 0, 0, 0 ]
gap>  GeneratorsOfGroup( G );
[ g1, g2, g3, g4 ]
gap>  GeneratorsOfGroup( D );
[ g2^-2, g3^-2, g4^2 ]

# an ordinary pcp for G / D
gap> pcp1 := Pcp( G, D );
Pcp [ g1, g2, g3, g4 ] with orders [ 2, 2, 2, 2 ]

# a pcp for G/D in independent generators
gap>  pcp2 := Pcp( G, D, "snf" );
Pcp [ g2, g3, g1 ] with orders [ 2, 2, 4 ]

gap>  g := Random( G );
g1*g2^-4*g3*g4^2

# compute the exponent vector of g in G/D with respect to pcp1
gap> ExponentsByPcp( pcp1, g );
[ 1, 0, 1, 0 ]

# compute the exponent vector of g in G/D with respect to pcp2
gap>  ExponentsByPcp( pcp2, g );
[ 0, 1, 1 ]
]]></Example>
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Factor groups of pcp-groups">
<Heading>Factor groups of pcp-groups</Heading>

Pcp's for subfactors of  pcp-groups have already been described above.
These are usually used within  algorithms to compute with  pcp-groups.
However, it is also possible to explicitly construct factor groups and
their corresponding natural homomorphisms.

<ManSection>
<Meth Name="NaturalHomomorphismByNormalSubgroup" Arg="G, N"/>
<Description>
	returns  the natural homomorphism   <M>G \to  G/N</M>.  Its image  is the
	factor group <M>G/N</M>.
</Description>
</ManSection>

<ManSection>
<Meth Name="\/" Arg='G, N'/>
<!-- <Oper Name="<C>G/N</C>{factor group}"/> FIXME -->
<Meth Name="FactorGroup" Arg="G, N"/>
<Description>
	returns  the desired factor as  pcp-group without  giving the explicit
	homomorphism. This function is just a wrapper for
	<C>PcpGroupByPcp( Pcp( G, N ) )</C>.
</Description>
</ManSection>

</Section>


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

&Polycyclic; provides code for defining group homomorphisms by
generators  and images where either the source or the range or both
are pcp groups. All methods provided by GAP for such group
homomorphisms are supported, in particular the following:

<ManSection>
<Func Name="GroupHomomorphismByImages" Arg="G, H, gens, imgs"/>
<Description>
	returns the homomorphism from the (pcp-) group <A>G</A> to the pcp-group <A>H</A>
	mapping the generators of <A>G</A> in the  list <A>gens</A> to the corresponding
	images in the list <A>imgs</A> of elements of <A>H</A>.
</Description>
</ManSection>

<ManSection>
<Func Name="Kernel" Arg="hom"/>
<Description>
	returns the kernel of  the homomorphism <A>hom</A> from   a pcp-group to  a
	pcp-group.
</Description>
</ManSection>

<ManSection>
<Oper Name="Image" Arg="hom"/>
<Func Name="Image" Arg="hom, U"/>
<Func Name="Image" Arg="hom, g"/>
<Description>
	returns the image of the whole group, of <A>U</A> and of <A>g</A>, respectively,
	under the homomorphism <A>hom</A>.
</Description>
</ManSection>

<ManSection>
<Func Name="PreImage" Arg="hom, U"/>
<Description>
	returns   the  complete  preimage of    the   subgroup <A>U</A>  under  the
	homomorphism <A>hom</A>.  If the domain of <A>hom</A> is  not a pcp-group, then
	this function only works properly if <A>hom</A> is injective.
</Description>
</ManSection>

<ManSection>
<Meth Name="PreImagesRepresentative" Arg="hom, g"/>
<Description>
	returns a preimage of the element <A>g</A> under the homomorphism <A>hom</A>.
</Description>
</ManSection>

<ManSection>
<Meth Name="IsInjective" Arg="hom"/>
<Description>
	checks if the homomorphism <A>hom</A> is injective.
</Description>
</ManSection>


</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Changing the defining pc-presentation">
<Heading>Changing the defining pc-presentation</Heading>

<ManSection>
<Func Name="RefinedPcpGroup" Arg="G"/>
<Description>
	returns a new  pcp-group isomorphic to  <A>G</A>  whose defining polycyclic
	presentation is refined;  that is, the corresponding polycyclic series
	has  prime or infinite  factors only. If  <M>H</M> is  the  new group, then
	<M>H!.bijection</M> is the isomorphism <M>G \to H</M>.
</Description>
</ManSection>

<ManSection>
<Func Name="PcpGroupBySeries" Arg="ser[, flag]"/>
<Description>
	returns a  new pcp-group isomorphic to  the first subgroup  <M>G</M> of the
	given  series <A>ser</A>  such  that  its defining  pcp  refines the  given
	series.  The  series  must  be  subnormal and  <M>H!.bijection</M>  is  the
	isomorphism  <M>G \to  H</M>.  If the  parameter <A>flag</A> is present
	and equals the string <Q>snf</Q>, the  series  must have
	abelian  factors.  The  pcp of  the  group returned  corresponds to  a
	decomposition of each  abelian factor into a direct  product of cyclic
	groups.

<Example><![CDATA[
gap> G := DihedralPcpGroup(0);
Pcp-group with orders [ 2, 0 ]
gap>  U := Subgroup( G, [Pcp(G)[2]^1440]);
Pcp-group with orders [ 0 ]
gap>  F := G/U;
Pcp-group with orders [ 2, 1440 ]
gap> RefinedPcpGroup(F);
Pcp-group with orders [ 2, 2, 2, 2, 2, 2, 3, 3, 5 ]

gap> ser := [G, U, TrivialSubgroup(G)];
[ Pcp-group with orders [ 2, 0 ],
  Pcp-group with orders [ 0 ],
  Pcp-group with orders [  ] ]
gap>  PcpGroupBySeries(ser);
Pcp-group with orders [ 2, 1440, 0 ]
]]></Example>
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Printing a pc-presentation">
<Heading>Printing a pc-presentation</Heading>

By default, a pcp-group is printed using its relative orders only. The
following methods can be used to view the pcp presentation of the group.

<ManSection>
<Func Name="PrintPcpPresentation" Arg="G[, flag]"/>
<Func Name="PrintPcpPresentation" Arg="pcp[, flag]"/>
<Description>
	prints the pcp presentation defined by the igs of <A>G</A> or the pcp <A>pcp</A>.

	By default, the trivial conjugator relations are omitted from this
	presentation to shorten notation. Also, the relations obtained from
	conjugating with inverse generators are included only if the conjugating
	generator has infinite order. If this generator has finite order, then
	the conjugation relation is a consequence of the remaining relations.

	If the  parameter <A>flag</A> is present and equals the string <Q>all</Q>,
	all conjugate relations are printed, including the trivial conjugate
	relations as well as those involving conjugation with inverses.
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Converting to and from a presentation">
<Heading>Converting to and from a presentation</Heading>

<ManSection>
<Attr Name="IsomorphismPcpGroup" Arg="G"/>
<Description>
	returns an isomorphism from <A>G</A> onto a pcp-group <A>H</A>. There are various
	methods installed for this operation and some of these methods are part
	of the &Polycyclic; package, while others may be part of other packages.
	<P/>

	For example, &Polycyclic; contains methods for this function in the case
	that <A>G</A> is a finite pc-group or a finite solvable permutation group.
	<P/>

	Other examples for methods for IsomorphismPcpGroup are the methods for
	the case that <A>G</A> is a crystallographic group (see &Cryst;) or the case
	that <A>G</A> is an almost crystallographic group (see &AClib;). A method for
	the case that <A>G</A> is a rational polycyclic matrix group is included in
	the &Polenta; package.
</Description>
</ManSection>

<ManSection>
<Func Name="IsomorphismPcpGroupFromFpGroupWithPcPres" Arg="G"/>
<Description>
	This function can convert a finitely presented group with a polycyclic
	presentation into a pcp group.
</Description>
</ManSection>

<ManSection>
<Meth Name="IsomorphismPcGroup" Arg="G"/>
<Description>
	pc-groups are a representation for finite polycyclic groups. This function
	can convert finite pcp-groups to pc-groups.
</Description>
</ManSection>

<ManSection>
<Meth Name="IsomorphismFpGroup" Arg="G"/>
<Description>
	This function can convert pcp-groups to a finitely presented group.
</Description>
</ManSection>

</Section>
</Chapter>