#############################################################################
##
## This file is part of GAP, a system for computational discrete algebra.
## This file's authors include Werner Nickel.
##
## Copyright of GAP belongs to its developers, whose names are too numerous
## to list here. Please refer to the COPYRIGHT file for details.
##
## SPDX-License-Identifier: GPL-2.0-or-later
##
#############################################################################
##
#F AbelianPQuotient . . . . . . . . . . . initialize an abelian p-quotient
##
## <ManSection>
## <Func Name="AbelianPQuotient" Arg='qs'/>
##
## <Description>
## </Description>
## </ManSection>
##
DeclareGlobalFunction( "AbelianPQuotient" );
#############################################################################
##
#F PQuotient(<F>, <p>[, <c>][, <logord>][, <ctype>]) . . pq of an fp group
##
## <#GAPDoc Label="PQuotient">
## <ManSection>
## <Func Name="PQuotient" Arg='F, p[, c][, logord][, ctype]'/>
##
## <Description>
## computes a factor <A>p</A>-group of a finitely presented group <A>F</A>
## in form of a quotient system.
## The quotient system can be converted into an epimorphism from <A>F</A>
## onto the <A>p</A>-group computed by the function
## <Ref Oper="EpimorphismQuotientSystem"/>.
## <P/>
## For a group <M>G</M> define the exponent-<M>p</M> central series of
## <M>G</M> inductively by <M>{\cal P}_1(G) = G</M> and
## <M>{\cal P}_{{i+1}}(G) = [{\cal P}_i(G),G]{\cal P}_{{i+1}}(G)^p</M>.
## The factor groups modulo the terms of the lower
## exponent-<M>p</M> central series are <M>p</M>-groups.
## The group <M>G</M> has <M>p</M>-class
## <M>c</M> if <M>{\cal P}_c(G) \neq {\cal P}_{{c+1}}(G) = 1</M>.
## <P/>
## The algorithm computes successive quotients modulo the terms of the
## exponent-<M>p</M> central series of <A>F</A>.
## If the parameter <A>c</A> is present,
## then the factor group modulo the <M>(c+1)</M>-th term of the
## exponent-<M>p</M> central series of <A>F</A> is returned.
## If <A>c</A> is not present, then the algorithm attempts to compute the
## largest factor <A>p</A>-group of <A>F</A>.
## In case <A>F</A> does not have a largest factor <A>p</A>-group,
## the algorithm will not terminate.
## <P/>
## By default the algorithm computes only with factor groups of order at
## most <M>p^{256}</M>. If the parameter <A>logord</A> is present, it will
## compute with factor groups of order at most <M>p^{<A>logord</A>}</M>.
## If this parameter is specified, then the parameter <A>c</A> must also be
## given. The present
## implementation produces an error message if the order of a
## <M>p</M>-quotient exceeds <M>p^{256}</M> or <M>p^{<A>logord</A>}</M>,
## respectively.
## Note that the order of intermediate <M>p</M>-groups may be larger than
## the final order of a <M>p</M>-quotient.
## <P/>
## The parameter <A>ctype</A> determines the type of collector that is used
## for computations within the factor <A>p</A>-group.
## <A>ctype</A> must either be <C>"single"</C> in which case a simple
## collector from the left is used or <C>"combinatorial"</C> in which case
## a combinatorial collector from the left is used.
## </Description>
## </ManSection>
## <#/GAPDoc>
##
DeclareGlobalFunction( "PQuotient" );
#############################################################################
##
#O EpimorphismPGroup( <fpgrp>, <p>[, <cl>] ) factor p-group of a f.p. group
##
## <#GAPDoc Label="EpimorphismPGroup">
## <ManSection>
## <Oper Name="EpimorphismPGroup" Arg='fpgrp, p[, cl]'/>
##
## <Description>
## computes an epimorphism from the finitely presented group <A>fpgrp</A> to
## the largest <M>p</M>-group of <M>p</M>-class <A>cl</A> which is
## a quotient of <A>fpgrp</A>.
## If <A>cl</A> is omitted, the largest finite <M>p</M>-group quotient
## (of <M>p</M>-class up to <M>1000</M>) is determined.
## <P/>
## <Example><![CDATA[
## gap> hom:=EpimorphismPGroup(fp,2);
## [ f1, f2 ] -> [ a1, a2 ]
## gap> Size(Image(hom));
## 8
## gap> hom:=EpimorphismPGroup(fp,3,7);
## [ f1, f2 ] -> [ a1, a2 ]
## gap> Size(Image(hom));
## 6561
## ]]></Example>
## </Description>
## </ManSection>
## <#/GAPDoc>
##
DeclareOperation( "EpimorphismPGroup", [IsGroup, IsPosInt ] );
DeclareOperation( "EpimorphismPGroup", [IsGroup, IsPosInt, IsPosInt] );
#############################################################################
##
#O EpimorphismQuotientSystem(<quotsys>)
##
## <#GAPDoc Label="EpimorphismQuotientSystem">
## <ManSection>
## <Oper Name="EpimorphismQuotientSystem" Arg='quotsys'/>
##
## <Description>
## For a quotient system <A>quotsys</A> obtained from the function
## <Ref Func="PQuotient"/>, this operation returns an epimorphism
## <M><A>F</A> \rightarrow <A>P</A></M> where <M><A>F</A></M> is the
## finitely presented group of which <A>quotsys</A> is a quotient system and
## <M><A>P</A></M> is a pc group isomorphic to the quotient of <A>F</A>
## determined by <A>quotsys</A>.
## <P/>
## Different calls to this operation will create different groups <A>P</A>,
## each with its own family.
## <P/>
## <Example><![CDATA[
## gap> PQuotient( FreeGroup(2), 5, 10, 1024, "combinatorial" );
## <5-quotient system of 5-class 10 with 520 generators>
## gap> phi := EpimorphismQuotientSystem( last );
## [ f1, f2 ] -> [ a1, a2 ]
## gap> Collected( Factors( Size( Image( phi ) ) ) );
## [ [ 5, 520 ] ]
## ]]></Example>
## </Description>
## </ManSection>
## <#/GAPDoc>
##
DeclareOperation( "EpimorphismQuotientSystem", [IsQuotientSystem] );
#############################################################################
##
#F EpimorphismNilpotentQuotient( <fpgrp>[, <n>] )
##
## <#GAPDoc Label="EpimorphismNilpotentQuotient">
## <ManSection>
## <Func Name="EpimorphismNilpotentQuotient" Arg='fpgrp[, n]'/>
##
## <Description>
## returns an epimorphism on the class <A>n</A> finite nilpotent quotient of
## the finitely presented group <A>fpgrp</A>.
## If <A>n</A> is omitted, the largest finite nilpotent quotient
## (of <M>p</M>-class up to <M>1000</M>) is taken.
## <P/>
## <Example><![CDATA[
## gap> hom:=EpimorphismNilpotentQuotient(fp,7);
## [ f1, f2 ] -> [ f1*f4, f2*f5 ]
## gap> Size(Image(hom));
## 52488
## ]]></Example>
## <P/>
## A related operation which is also applicable to finitely presented groups is
## <Ref Oper="GQuotients"/>, which computes all epimorphisms from a
## (finitely presented) group <A>F</A> onto a given (finite) group <A>G</A>.
## <P/>
## <Example><![CDATA[
## gap> GQuotients(fp,Group((1,2,3),(1,2)));
## [ [ f1, f2 ] -> [ (1,2), (2,3) ], [ f1, f2 ] -> [ (2,3), (1,2,3) ],
## [ f1, f2 ] -> [ (1,2,3), (2,3) ] ]
## ]]></Example>
## </Description>
## </ManSection>
## <#/GAPDoc>
##
DeclareOperation("EpimorphismNilpotentQuotientOp",[IsGroup,IsObject]);
DeclareGlobalFunction("EpimorphismNilpotentQuotient");
#############################################################################
##
#O Nucleus . . . . . . . . . . . . . . . . . . . . the nucleus of a p-cover
##
## <ManSection>
## <Func Name="Nucleus" Arg='pq, G'/>
##
## <Description>
## </Description>
## </ManSection>
##
DeclareOperation("Nucleus",[IsPQuotientSystem,IsGroup]);
