%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  func.tex		NQL Doc				Rene Hartung
%%
%H  $Id: func.tex,v 1.5 2007/05/25 08:30:53 gap Exp $
%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Chapter{The underlying functions}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Nilpotent Quotient Systems for invariant L-presentations}

For an L-presented group $G$ which is given by an invariant L-presentation
a polycyclic presentation for 
%display{nonhtml}
$G/\gamma_{c+1}(G)$ 
%enddisplay
%display{html}
%<var>G/&gamma;<sub>c+1</sub>(G)</var>
%enddisplay
is computed by determine
a weighted nilpotent quotient system for $G/G'$ and extending it 
inductively to a quotient system for 
%display{nonhtml}
$G/\gamma_{c+1}(G)$.  
%enddisplay
%display{html}
%<var>G/&gamma;<sub>c+1</sub>(G)</var>.
%enddisplay

A quotient system in the {\NQL} package is a record containing the 
following entries:

\beginitems
<Lpres> & the (invariant) L-presentation of the quotient system.

<Pccol> & `FromTheLeftCollector' of the nilpotent quotient represented by this 
	  quotient system.

<Imgs>  & images of the generators of the L-presented group under the 
	  epimorphism onto the nilpotent quotient <Pccol>. 
          For each generator of the L-presented group <Lpres>
   	  there is an integer or a generator exponent list. If the image 
	  is an integer <int> the image is a definition of the <int>-th
 	  generator of the nilpotent presentation <Pccol>.

<Epimorphism>& epimorphism from the L-presented group <Lpres> onto its 
	       nilpotent quotient <Pccol> with the images of the generators
	       given by <Imgs>.

<Weights> & weight of each generator of the nilpotent presentation <Pccol>.

<Definitions>
       & the definition of each generator of <Pccol>. Each generator in the 
	 quotient system has a definition as an image or as a commutator of the 
	 form $[a_j,a_i]$ where $a_j$ and $a_i$ are generators of a certain
	 weight. If the <i>-th entry is an integer, the <i>-th generator of
 	 <Pccol> has a definition as an image. Otherwise the <i>-th entry is
	 a 2-tuple $[k,l]$ and the <i>-th generator has a definition as
         commutator $[a_k,a_l]$.
\enditems

A quotient system of an L-presented group given by an invariant L-presentation 
can be computed by the following functions. Both are implemented in the
`NilpotentQuotientLpGroup'- and `NqEpimorphismNilpotentQuotientLpGroup' method.

\> InitQuotientSystem( <LpGroup> )

returns a weighted nilpotent quotient system for the largest Abelian
quotient of the L-presented group <LpGroup>.

\> ExtendQuotientSystem( <QS> )

extends the weighted nilpotent quotient system <QS>
of an L-presented group given by an invariant L-presentation.

\beginexample
gap> G:=ExamplesOfLPresentations(1);
<L-presented group on the generators [ a, b, c, d ]>
gap> Q:=InitQuotientSystem(G);
rec( Lpres := <L-presented group on the generators [ a, b, c, d ]>, 
  Pccol := <<from the left collector with 3 generators>>, 
  Imgs := [ 1, [ 2, 1, 3, 1 ], 2, 3 ], Epimorphism := [ a, b, c, d ] -> 
    [ g1, g2*g3, g2, g3 ], Weights := [ 1, 1, 1 ], Definitions := [ 1, 3, 4 ] 
 )
gap> ExtendQuotientSystem(Q);
rec( Lpres := <L-presented group on the generators [ a, b, c, d ]>, 
  Pccol := <<from the left collector with 5 generators>>, 
  Imgs := [ 1, [ 2, 1, 3, 1 ], 2, 3 ], 
  Definitions := [ 1, 3, 4, [ 2, 1 ], [ 3, 1 ] ], 
  Weights := [ 1, 1, 1, 2, 2 ], Epimorphism := [ a, b, c, d ] -> 
    [ g1, g2*g3, g2, g3 ] )
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Attributes of L-presented groups}

To avoid repeated extensions of quotient systems the largest known
quotient system is stored as an attribute of the invariant L-presentation. For 
non-invariant L-presentations the known nilpotent quotients and its epimorphisms
are stored as an attribute. 

\> NilpotentQuotientSystem( <LpGroup> ) A

returns the largest known nilpotent quotient system of an L-presented group 
that is given by an invariant L-presentation.

\beginexample
gap> G:=ExamplesOfLPresentations(1);;
gap> NilpotentQuotientLpGroup(G,5);
Pcp-group with orders [ 2, 2, 2, 2, 2, 2, 2, 2, 2, 2 ]
gap> NilpotentQuotientSystem(G);
rec( Lpres := <L-presented group on the generators [ a, b, c, d ]>, 
  Pccol := <<from the left collector with 10 generators>>, 
  Imgs := [ 1, [ 2, 1, 3, 1 ], 2, 3 ], 
  Definitions := [ 1, 3, 4, [ 2, 1 ], [ 3, 1 ], [ 4, 2 ], [ 4, 3 ], [ 7, 1 ], 
      [ 8, 2 ], [ 8, 3 ] ], Weights := [ 1, 1, 1, 2, 2, 3, 3, 4, 5, 5 ], 
  Epimorphism := [ a, b, c, d ] -> [ g1, g2*g3, g2, g3 ] )
gap> NilpotencyClassOfGroup(PcpGroupByCollectorNC(last.Pccol));
5
\endexample

\> NilpotentQuotients( <LpGroup> ) A

returns all known nilpotent quotients of the non-invariant L-presentation
<LpGroup>.

\beginexample
gap> G:=ExamplesOfLPresentations(3);;
gap> HasIsInvariantLPresentation(G);
false
gap> NilpotentQuotientLpGroup(G,3);
Pcp-group with orders [ 2, 0, 2, 2 ]
gap> NilpotentQuotients(G);
[ rec( Quotient := Pcp-group with orders [ 2, 0 ], 
      Epimorphism := [ a, b, t ] -> [ g1, g1, g2 ] ), 
  rec( Quotient := Pcp-group with orders [ 2, 0, 2 ], 
      Epimorphism := [ a, b, t ] -> [ g1, g1, g2 ] ), 
  rec( Quotient := Pcp-group with orders [ 2, 0, 2, 2 ], 
      Epimorphism := [ a, b, t ] -> [ g1, g1, g2 ] ) ]
gap> NilpotentQuotientSystem(UnderlyingInvariantLPresentation(G));
rec( Lpres := <L-presented group on the generators [ a, b, t ]>, 
  Pccol := <<from the left collector with 9 generators>>, Imgs := [ 1, 2, 3 ],
  Definitions := [ 1, 2, 3, [ 3, 1 ], [ 3, 2 ], [ 4, 1 ], [ 5, 2 ], [ 4, 3 ], 
      [ 5, 3 ] ], Weights := [ 1, 1, 1, 2, 2, 3, 3, 3, 3 ], 
  Epimorphism := [ a, b, t ] -> [ g1, g2, g3 ] )
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{The Info-Class InfoNQL}

To get some information about the progress of the algorithm,
one can use the info class `InfoNQL'. 

\> InfoNQL

is the info class of the {\NQL}-package. It gives further information
on the progress of the nilpotent quotient algorithm for L-presented 
groups.

\beginexample
gap> SetInfoLevel(InfoNQL,1);;
gap> G:=ExamplesOfLPresentations(1);
#I  The first Grigorchuk group on 4 generators
<L-presented group on the generators [ a, b, c, d ]>
gap> NilpotentQuotientLpGroup(G,5);
#I  Class 1: 3 generators with relative orders: [ 2, 2, 2 ]
#I  Class 2: 2 generators with relative orders: [ 2, 2 ]
#I  Class 3: 2 generators with relative orders: [ 2, 2 ]
#I  Class 4: 1 generators with relative orders: [ 2 ]
#I  Class 5: 2 generators with relative orders: [ 2, 2 ]
Pcp-group with orders [ 2, 2, 2, 2, 2, 2, 2, 2, 2, 2 ]
gap> NilpotentQuotientLpGroup(G,10);
#I  Class 6: 2 generators with relative orders: [ 2, 2 ]
#I  Class 7: 1 generators with relative orders: [ 2 ]
#I  Class 8: 1 generators with relative orders: [ 2 ]
#I  Class 9: 2 generators with relative orders: [ 2, 2 ]
#I  Class 10: 2 generators with relative orders: [ 2, 2 ]
Pcp-group with orders [ 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2 ]
\endexample

\> InfoNQL_MAX_GENS 

this global variable sets the limit of generators whose relative order will be
shown on each step of the nilpotent quotient algorithm if the 'InfoLevel' of 
`InfoNQL' is positive.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
