
The ANU Nilpotent Quotient Program
==================================

Nilpotent quotients
-------------------

The lower central series  G_i of a group  G can be defined inductively
as G_0 = G, G_i = [G_(i-1),G]. G is said to have nilpotency class c if
c is the smallest non-zero integer such that G_c = 1. If N is a normal
subgroup  of G and  G/N is nilpotent, then N  contains   G_i  for some
non-negative integer i. G has infinite nilpotent quotients if and only
if G/G_1 is infinite and a prime p divides a finite cyclic factor of a
nilpotent quotient if and only if p  divides a cyclic factor of G/G_1.
The i-th (i  > 1) factor  G_(i-1)/G_i of the  lower central series  is
generated by the elements  [g,h]G_i,  where g  runs through  a  set of
representatives of G/G_1 and h  runs through a set of  representatives
of G_(i-2)/G_(i-1).

Any finitely generated  nilpotent group is polycyclic and,  therefore,
has a  subnormal series with  cyclic factors.  Such a subnormal series
can be   used  to  represent the   group  in terms  of    a polycyclic
presentation.  The ANU  NQ computes  successively  the  factor  groups
modulo the terms of  the  lower central series.   Each factor group is
represented by a special form of polycyclic  presentation, a nilpotent
presentation, that makes use of the  nilpotent structure of the factor
group.   Chapters 9  and 11  of  a forthcoming  book  by C.C.    Sims,
"Computing  with finitely  presented  groups",  discusses   polycyclic
presentations and a nilpotent quotient algorithm.

About this version
------------------

This   directory  contains  Version 1.1  of  the  Australian  National
University Nilpotent Quotient Program (ANU NQ), an implementation of a
nilpotent quotient  algorithm  in C.   This  implementation  has  been
developed in  a  Unix environment  and  Unix  is  currently  the  only
operating  system supported.  It  runs on  a  number of different Unix
versions, e.g.  SunOS and Ultrix. This version of  the ANU NQ  is also
available as part of quotpic  (Derek F.  Holt,  Sarah Rees: A graphics
system for  displaying finite quotients of finitely  presented groups.
DIMACS Workshop on Groups and Computation, AMS-ACM 1991).

This directory contains the following directories and files:

          README
          examples
          gap
          src
          testNq

The  file `README'  is (what a  surprise!)  this file.   The directory
`examples' contains a   collection  of  example input files    for the
nilpotent quotient  program.   The directory `gap'  contains   the GAP
interface to the ANU NQ. The program system GAP is developed by Martin
Schoenert et al. at  the RWTH Aachen,  Germany.  The  directory  `src'
contains the source code for the ANU NQ  and the  file `testNq' can be
run to test if the installation of the ANU NQ is working properly (see
next section).  It uses the groups in the directory `examples'.

How to install the ANU NQ
-------------------------

The installation of  the program is  easy.   However, it requires  the
Berkeley  compatible interface of  the  GNU multiple precision library
(GNU  MP).  GNU is the Free  Software Foundation's collection  of UNIX
compatible software. If this library  is not available on your system,
it has to be  installed first.  A copy of  GNU MP can be  obtained via
anonymous ftp from many file servers around the world, for example:

        prep.ai.mit.edu:/pub/gnu/gmp-1.2.tar.Z
        archie.au:/gnu/gmp-1.2.tar.Z
	pell.anu.edu.au:/pub/gmp-1.2.tar.Z

Once GNU MP has been installed,  go into the  directory `src' and edit
the file `Makefile'. It contains the following lines:

##    The following two line define the name of the GNU multiple precision
##    library (GNULIB) and the directory that contains the corresponding
##    include files (GNUINC).
GNULIB = /usr/local/lib/libmp.a
GNUINC = /usr/local/include

The definition of `GNULIB' has to be changed to the name of the GNU MP
library on your system.  The definition of `GNUINC'  has to be changed
to  the directory  on   your system  that contains the   corresponding
include files.

After this change you start the compilation of the ANU NQ by typing

	make

A compiled version of the program named  `nq'  is then placed into the
directory `src'.    If  there are  any warnings   or  even fatal error
messages during  the compilation process,  please send a copy  to  the
address at the  end of  this document together  with information about
your operating system, the compiler you used and any changes you might
have made to the source code. I will have a look  at your problems and
try to fix them.
 
After the compilation  is finished you   can  check if the ANU  NQ  is
running properly on your system.  Go back to  the parent directory and
type

    testNq

The file testNq runs some  computations and compares their output with
the output files in  the directory `examples'.  If testNq reports  any
errors, please follow the instruction that testNq prints out.
 
How to use the ANU NQ
---------------------

If you start the ANU  NQ by typing
     nq

you will get the following message:
    usage: nq [-d] [-g] [-v] [-t <n>] [-l <n>] [-r <n>] [-e <n>]
              <presentation>  [<class>]

All parameters  in    square brackets are   optional.   The  parameter
<presentation>  has  to be the name of  a file  that contains a finite
group presentation for which a nilpotent quotient is to be calculated.
The  parameter  <class> restricts   the  computation of  the nilpotent
quotient  to  at most that  (nilpotency)   class,   i.e.  the  program
calculates the  quotient group of  the  (c+1)-th term  of   the  lower
central   series.   If   <class>  is   omitted,  the program  computes
successively the factor  groups of  the lower  central  series of  the
given group.  If there is  a largest nilpotent  quotient, i.e., if the
lower  central series  becomes  constant,  the program will eventually
terminate with the largest nilpotent quotient.  If there is no largest
nilpotent quotient,  the  program will run  forever (or more precisely
will  run out   of resources).  On termination  the  program prints  a
nilpotent presentation for the nilpotent quotient it has computed.

The options -l, -r and  -e can be used  to enforce Engel conditions on
the nilpotent quotient to be calculated.  All these options have to be
followed by a positive integer <n>. Their meaning is the following:

        -l <n> This forces the   first generator g  of  the  nilpotent
               quotient  Q to  be a  left   n-Engel   element, i.e., g
               satisfies [x,...,x,g] = 1 (x occurring n-times) for all
               x in Q.

        -r <n> This  makes the  first   generator  g of  the nilpotent
               quotient Q a  right n-Engel element,  i.e., g satisfies
               [g,x,..,x] = 1 (x occurring n-times) for all x in Q.
               
        -e <n> This enforces the n-th Engel law on Q, i.e., [x,y,..,y]
               = 1 (y occurring n-times) for all x,y in Q.

        -t <n> This option specifies how much  CPU time the program is
               allowed to use. It will terminate after  <n> seconds of
               CPU time.  If <n> is followed (without space) by one of
               the letters  m,   h or d,  <n>  specifies the  time  in
               minutes, hours or days, respectively.

The options -d, -v and -g have the following meaning:

        -d Switch   on debug mode    and   perform checks  during  the
           computation. Not yet implemented.

        -v Switch on verbose mode.

        -g Produce GAP output. Presently the  GAP output consists only
           of a sequence of integer matrices  whose rows are relations
           of  the  factors of  the lower central  series  as  abelian
           groups. This will change as soon as GAP can handle infinite
           polycyclic groups.


The input format for presentations
----------------------------------

The  input  format for  finite presentations resembles  the  way  many
people write down a presentation on paper.  Here are  some examples of
presentations that the ANU NQ accepts:

    < a, b | >                       # free group of rank 2

    < a, b, c | [a,b,c],             # a left normed commutator
                [b,c,c,c]^6,         # another one raised to a power
                a^2 = c^-3*a^2*c^3,  # a relation
                a^(b*c) = a,         # a conjugate relation
                (a*[b,(a*c)])^6      # something that looks complicated
    >

A presentation starts  with   '<' followed be  a  list   of generators
separated by  commas.  Generator  names are strings  that contain only
upper and lower case letters, digits, dots and underscores and that do
not start with a digit.  The list of generator names is separated from
the   list of relators/relations   by  the symbol  '|'.  Relators  and
relations  are separated  by  commas and  can   be  mixed arbitrarily.
Parentheses can be  used  in order  to  group subexpressions together.
Square brackets can be used in order  to form left normed commutators.
The symbols  '*'  and '^' can be  used  to   form products and powers,
respectively. The  presentation   finishes  with  the  symbol '>'.   A
comment  starts with the symbol  '#' and  finishes at  the  end of the
line.  The file src/presentation.c contains a complete grammar for the
presentations accepted by the ANU NQ.

An example
----------

Let G be  the free group  on two generators  x  and y. The input  file
(called free2.fp here) contains the following:

        < x, y | >

Computing the class 3 quotient with the ANU NQ by typing

        nq free2.fp 3

produces the following output:
#
#    The ANU Nilpotent Quotient Program (Version 1.1, 22 Jan 1993)
#    Calculating a nilpotent quotient
#    Input: free2.fp
#    Nilpotency class: 3
#    Program: ./nq     Machine: lamb
#
#    Calculating the abelian quotient ...
#    The abelian quotient has 2 generators
#        with the following exponents: 0 0
#
#    Calculating the class 2 quotient ...
#    Layer 2 of the lower central series has 1 generators
#          with the following exponents: 0
#
#    Calculating the class 3 quotient ...
#    Layer 3 of the lower central series has 2 generators
#          with the following exponents: 0 0
#


#    The epimorphism :
#    a|---> A
#    b|---> B


#    The nilpotent quotient :
    <A,B,C,D,E
      |
        B^A           =: B*C,
        B^(A^-1)      =  B*C^-1*D,
        C^A           =: C*D,
        C^(A^-1)      =  C*D^-1,
        C^B           =: C*E,
        C^(B^-1)      =  C*E^-1 >

#    Class : 3
#    Nr of generators of each class : 2 1 2

#    total runtime : 0 msec
#    total size    : 24584 byte

Most of the comments are fairly self-explanatory. One  note of caution
is necessary:  The  number of generators for each  factor of the lower
central series is not the minimal number possible but is the number of
generators that the ANU NQ chose to use. This will be  improved in one
of   the future  version of  the  program.  The epimorphism  from  the
original group  onto the nilpotent  quotient  is printed in a somewhat
confusing way.  The generators on  the left  hand  side of the  arrows
correspond to  the  generators  in the original  presentation  but are
printed with different names.  This  will be  fixed in one of the next
version.

Some remarks about the algorithm
--------------------------------

The implementation of  the algorithm is fairly  straight forward.  The
program  uses a   weighted nilpotent  presentation with definitions to
represent a nilpotent group.  Calculations in the nilpotent  group are
done using a collector from the left without combinatorial collection.
Generators  for  the  c-th   lower central  factor  are    defined  as
commutators of the form [y,x], where x is a generator  of weight 1 and
y  is   a generator of weight c-1.    Then the program calculates  the
necessary changes (tails) for all relations which are not definitions,
runs  through  the consistency   check and evaluates    the   original
relations on the polycyclic presentation.  This gives a list of words,
which have  to   be  made trivial  in  order  to  obtain a  consistent
polycyclic presentation representing a nilpotent quotient of the given
finitely presented   group.  This list   is converted into   a integer
matrix, which  is transformed  into upper   triangular form using  the
Kannan-Bachem  algorithm.  The GNU multiple  precision package is used
for this.


Some improvements planned for further versions
----------------------------------------------

On the agenda for  future versions  of  the program are  the following
items :

	Use combinatorial collection
	Improve the speed of checking the Engel conditions
	Avoid consistency tests used for tail computations
	Speed up elimination of generators and extending the pc pres
	Early recognition that the multiplier collapses
	Use column permutations in the Kannan-Bachem algorithm
	Add more comments to the code
	Use the mpz-interface of the GNU multiple precision package
	Find a more satisfying solution for generating sets for each
	     central factor.
        Multiple precision integers as exponents of generators
	Better control over the output
        Output computed nilpotent quotient if the program times out

Contact addresses
-----------------
Comments and suggestions are very welcome, my email address is 

		werner@pell.anu.edu.au

Werner Nickel
Mathematics Research Section
School of Mathematical Sciences
Australian National University, Canberra, Australia
