%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  func.tex		NQL Doc				René Hartung
%%
%H  $Id: func.tex,v 1.8 2010/03/31 13:42:53 gap Exp $
%%

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

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

For an invariantly $L$-presented group $G$, our algorithm computes a
nilpotent presentation for $G/\gamma_{c+1}(G)$ by computing a <weighted
nilpotent quotient system> for $G/G'$ and extending it inductively to
a weighted nilpotent quotient system for $G/\gamma_{c+1}(G)$.

In the {\NQL} package, a weighted nilpotent quotient system is a record
containing the following entries:

\beginitems
<Lpres> & the invariantly $L$-presented group $G$.

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

<Imgs>  & the images of the generators of the $L$-presented group $G$ under
	  the epimorphism onto the nilpotent quotient <Pccol>. For
	  each generator of $G$ 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>& an epimorphism from the $L$-presented group $G$ onto its 
	       nilpotent quotient <Pccol> with the images of the generators
	       given by <Imgs>.

<Weights> & a list of the 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 weighted nilpotent quotient system of an invariantly $L$-presented group 
can be computed with the following functions. 

\> InitQuotientSystem( <LpGroup> ) O

computes a weighted nilpotent quotient system for the abelian quotient
of the $L$-presented group <LpGroup>.

\> ExtendQuotientSystem( <QS> ) O

extends the weighted nilpotent quotient system <QS> for a class-$c$
quotient of an invariantly $L$-presented group to a weighted nilpotent
quotient system of its class-$c+1$ quotient.

\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 related with the nilpotent quotient algorithm}

To avoid repeated extensions of a weighted nilpotent quotient system
the largest known quotient system is stored as an attribute of the
invariantly $L$-presented group. For non-invariantly $L$-presented groups
(or groups which are not known to be invariantly $L$-presented) the known
epimorphisms onto the nilpotent quotients are stored as an attribute.

\> NilpotentQuotientSystem( <LpGroup> ) A

stores the largest known weighted nilpotent quotient system of an
invariantly $L$-presented group.

\beginexample
gap> G := ExamplesOfLPresentations( 1 );;
gap> NilpotentQuotient( 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

stores all known epimorphisms onto the nilpotent quotients of <LpGroup>.
The nilpotent quotients are accessible by the operation `Range'.

\beginexample
gap> G:=ExamplesOfLPresentations( 3 );;
gap> HasIsInvariantLPresentation( G );
false
gap> NilpotentQuotient( G, 3 );
Pcp-group with orders [ 0, 2, 2, 2 ]
gap> NilpotentQuotients( G );
[ [ a, t, u ] -> [ g2, g1, g2 ], [ a, t, u ] -> [ g2, g1, g2 ],
  [ a, t, u ] -> [ g2, g1, g2 ] ]
gap> Range( last[2] );
Pcp-group with orders [ 0, 2, 2 ]
\endexample
The underlying invariant $L$-presentation has stored its largest
weighted nilpotent quotient system as an attribute.
\beginexample
gap> NilpotentQuotientSystem( UnderlyingInvariantLPresentation( G ) );
rec( Lpres := <L-presented group on the generators [ a, t, u ]>,
  Pccol := <<from the left collector with 9 generators>>, Imgs := [ 1, 2, 3 ],
  Definitions := [ 1, 2, 3, [ 2, 1 ], [ 3, 2 ], [ 4, 1 ], [ 4, 2 ], [ 5, 2 ],
      [ 5, 3 ] ], Weights := [ 1, 1, 1, 2, 2, 3, 3, 3, 3 ],
  Epimorphism := [ a, t, u ] -> [ 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. If the info-level is $1$, the
info-class gives further information on the progress of the nilpotent
quotient algorithm for $L$-presented groups. The info-level $2$ also
includes some information on the runtime of our algorithm while the
info-level $3$ is mainly used for debugging-purposes. An example of such
a session for the Grigorchuk group is shown below:

\beginexample
gap> SetInfoLevel( InfoNQL, 1 );;
gap> G:=ExamplesOfLPresentations( 1 );
#I  The Grigorchuk group on 4 generators
<L-presented group on the generators [ a, b, c, d ]>
gap> NilpotentQuotient( G, 3 );
#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 ]
Pcp-group with orders [ 2, 2, 2, 2, 2, 2, 2 ]
gap> SetInfoLevel( InfoNQL, 2 );
gap> NilpotentQuotient( G, 5 );
#I  Time spent for spinning algo:  0:00:00.004
#I  Class 4: 1 generators with relative orders: [ 2 ]
#I  Runtime for this step  0:00:00.028
#I  Time spent for spinning algo:  0:00:00.008
#I  Class 5: 2 generators with relative orders: [ 2, 2 ]
#I  Runtime for this step  0:00:00.036
Pcp-group with orders [ 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
info-level of `InfoNQL' is positive.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%E  func.tex  . . . . . . . . . . . . . . . . . . . . . . . . ends here
