The ANUPQ package
                            -----------------

The ANUPQ package is a GAP4 interface with the ANU pq C  program  written
by  Eamonn  O'Brien.  The  ANU  pq   C   program   provides   access   to
implementations of the following algorithms:

1. A p-quotient algorithm to compute a power-commutator presentation  for
a group of prime power order. The algorithm implemented here is based  on
that described in Newman and O'Brien (1996), Havas and Newman (1980), and
papers referred to there. Another description of the algorithm appears in
Vaughan-Lee (1990).  A  FORTRAN  implementation  of  this  algorithm  was
programmed by Alford  and  Havas.  The  basic  data  structures  of  that
implementation are retained.

2. A p-group generation algorithm to generate descriptions of  groups  of
prime power order.  The  algorithm  implemented  here  is  based  on  the
algorithms described in Newman  (1977)  and  O'Brien  (1990).  A  FORTRAN
implementation of this algorithm was  earlier  developed  by  Newman  and
O'Brien.

3. A  standard  presentation  algorithm  used  to  compute  a   canonical
power-commutator presentation of a  p-group.  The  algorithm  implemented
here is described in O'Brien (1994).

4. An algorithm which can be used to compute the automorphism group of  a
p-group. The algorithm implemented here is described in O'Brien (1994).

The following section describes the installation of the ANUPQ package.  A
description of the functions available in the ANUPQ package is  given  in
the  package  manual  in  the  doc  directory.  For  details  about   the
implementation and the standalone version see the README and guide.dvi in
the standalone-doc directory. As mentioned above the implementation in  C
was written by

Eamonn O'Brien
Department of Mathematics
University of Auckland
Private Bag 92019
Auckland
New Zealand

e-mail: obrien@math.auckland.ac.nz 

                       Obtaining the ANUPQ package
                       ---------------------------

Note  that, owing  to its  C  code component,  the ANUPQ  package can  be
installed  under UNIX or  in environments  similar to  UNIX. It  has been
tested  on DECstation  running  Ultrix,  a HP  9000/700  and HP  9000/800
running  HP-UX, a MIPS  running RISC/os  Berkeley, a  NeXTstation running
NeXTSTEP  3.0, SUNs  running SunOS  and Intel  Pentium based  PCs running
Linux or Windows equipped with cygwin.

You can download  `anupq-XXX.zoo' (where `XXX'  is  the  package  version
number) from the home page for the ANUPQ package

http://www.math.rwth-aachen.de/~Greg.Gamble/ANUPQ/ (Germany)

or the Australian mirror

http://www.maths.uwa.edu.au/~gregg/ANUPQ/          (Perth, Australia)

or via the Packages links from the GAP sites

http://www.gap-system.org/                         (UK)
http://www.math.rwth-aachen.de/~GAP/               (Germany)

or the GAP ftp servers

ftp://ftp-gap.dcs.st-and.ac.uk/pub/gap/gap4/zoo/packages/
ftp://ftp.math.rwth-aachen.de/pub/gap4/zoo/packages/

If you prefer tar.gz or tar.bz2 to zoo  archives,  substitute  tar.gz  or
tar.bz2 (as appropriate) for zoo in the above paths.

                      Installing the ANUPQ package
                      ----------------------------

To install the ANUPQ package, move the file  `anupq-<XXX>.zoo'  into  the
`pkg' directory in which you plan to install ANUPQ. Usually, this will be
the directory `pkg' in the hierarchy of your version of GAP 4.  (However,
it is also possible to keep an additional `pkg' directory in your private
directories, see section "ref:Installing  GAP  Packages"  of  the  GAP  4
reference manual for details on how to do this.)

For version 3.0 of the ANUPQ package, all pre-GAP 4.4  compatibility  was
removed, and the AutPGrp package became essential (not just recommended).
Thus at least version 4.4 of GAP and at least version 1.2 of the  AutPGrp
package are now required by the ANUPQ package.

If you still have GAP 4.3 (at least fix4), you will need to use ANUPQ 2.2
(it's not recommended but no known bugs exist with that ANUPQ version).

Then unzoo `anupq-<XXX>.zoo' by

  unzoo -x anupq-<XXX>

Change directory to the newly created `anupq' directory. Now you need  to
call `configure <path>'  where  <path>  is  the  path  to  the  GAP  home
directory. So for example if you install the package in  the  main  `pkg'
directory call

  ./configure ../..

This will fetch the architecture type for which  GAP  has  been  compiled
last, create a `Makefile' and list a number of ``targets'' to call `make'
with. If you have one of  the  standard  linux  (or  NetBSD  or  FreeBSD)
systems with `gcc', wish to compile with  `-O2'  optimisation,  and  have
`gmp' with its include and  library  files  in  `/usr/local/include'  and
`/usr/local/lib', respectively, you can now simply call

  make

to compile the binary and to install it in the appropriate place.

If you need a special target (perhaps you don't have `gmp' or you are not
on a linux, NetBSD or FreeBSD system) then you need to call `make' with a
target argument. If  the  targets  displayed  on  the  screen  after  the
`configure' step rushed past your eyes and you can't scroll back  to  see
them, you can ``pipe'' those same targets through `less' or `more',  e.g.
with `more':

  make unknown | more

An abbreviation of the target list is as follows:

'linux-iX86-gcc2-gmp'      for IBM x86 PCs under linux/BSD with GNU cc 2 and mp
'linux-iX86-cc-gmp'        for IBM x86 PCs under linux/BSD with cc and GNU mp
'linux-iX86-gcc2'          for IBM x86 PCs under linux/BSD with GNU cc 2
'linux-iX86-cc'            for IBM x86 PCs under linux/BSD with cc (GNU)
'iX86-pc-cygwin-gcc-gmp'   for IBM x86 PCs under CYGWIN with GNU cc and GNU mp
'iX86-pc-cygwin-gcc'       for IBM x86 PCs under CYGWIN with GNU cc
[... 16 lines deleted ...]
'sunos-gcc2-gmp'           for SunOS with GNU cc 2 and gmp
'sunos-cc-gmp'             for SunOS with cc and GNU mp
'sunos-gcc2'               for SunOS with GNU cc 2
'sunos-cc'                 for SunOS with cc
'unix-gmp'                 for a generic unix system with cc and GNU mp
'unix'                     for a generic unix system with cc
'clean'                    remove all created files

   targets are listed according to preference,
   i.e., 'sunos-gcc2' is better than 'sunos-cc'
   no target is the same as choosing 'linux-iX86-gcc2-gmp'
   additional C compiler and linker flags can be passed with
   'make <target> COPTS=<compiler-opts> LOPTS=<linker-opts>',
   e.g., 'make sunos-cc COPTS=-g LOPTS=-g'.

   set GAP if GAP4 is not started with the command 'gap',
   e.g., 'make sunos-cc GAP=/usr/local/bin/gap4'.

   in order to use the GNU multiple precision (gmp) set
   'GNUINC' (default '/usr/local/include') and 
   'GNULIB' (default '/usr/local/lib')

   do 'make unknown | more' to see these targets again via more

Let's suppose that the `linux-iX86-gcc2-gmp' target does not satisfy your
requirements; further suppose your system is Solaris 2.8 (i.e SunOS 5.8),
you have `gmp' but its include  and  library  directories  are  somewhere
else, and that `gap4' is the command used to initiate  GAP  4.  Then  the
following `make' call might be correct in this case:

  make sunos-gcc2-gmp GAP=gap4 GNUINC=/opt/local/include GNULIB=/opt/local/lib

If you  don't  have  the  *GNU*  multiple  precision  arithmetic  (`gmp')
installed on your system, not to worry, `gmp'  is  *not  required*;  just
select an appropriate target without `-gmp'.

The path of GAP (see *Note* below) used by the  `pq'  binary  (the  value
`GAP' is set to in the `make' command) may be over-ridden by setting  the
environment variable `ANUPQ_GAP_EXEC'. These values are only of  interest
when the `pq' program is run  as  a  standalone;  however,  the  `testPq'
script assumes you have set one of these correctly (see Section  "Testing
your ANUPQ installation"). When the `pq'  program  is  started  from  GAP
communication occurs via an iostream, so that the `pq'  binary  does  not
actually need to know a valid path for GAP is this case.

*Note.* By ``path of GAP'' we mean the path of the command used to invoke
GAP (which should be a script, e.g. the `gap.sh' script generated in  the
`bin' directory for the version of GAP when GAP was compiled). The  usual
strategy is to copy the `gap.sh' script  to  a  standard  location,  e.g.
`/usr/local/bin/gap'. It is a mistake to copy the  GAP  executable  `gap'
(in a directory  with  name  of  form  `bin/<compile-platform>')  to  the
standard location, since direct invocation of the executable  results  in
GAP starting without being able to find its own library (a fatal error).

              Establishing the ANUPQ package documentation
              --------------------------------------------

The ANUPQ package documentation source  files  are  found  in  the  `doc'
directory. There you should also find  `manual.dvi'.  It  should  not  be
necessary for you to re-create the documentation. An HTML version of  the
ANUPQ package manual is provided in the `htm' directory with initial page
`chapters.htm'. If you have deleted the TeX DVI version of the manual and
need to recreate it (and the `.lab' and `.toc' files are  still  present)
then just do

  tex manual

once in this directory to obtain `manual.dvi'. If  you  have  `pdftex'  a
`PDF' version is obtained just as easily:

  pdftex manual

generates `manual.pdf'. If you need a PostScript version, on most systems
a file `manual.ps' will be generated by

  tex manual; dvips manual -o

You can safely discard the  files  with  extensions  `.aux',  `.idx'  and
`.log'. Not too much harm is done by removing the files  with  extensions
`.lab' and `.toc'; just be aware that if you ever need to re-generate the
`.dvi' or `.pdf' file you will need to `tex' or `pdftex' twice  if  these
files are removed (the first `tex' or `pdftex' pass re-establishes  these
files). Although the `.six' file  is  re-generated  each  time  `tex'  or
`pdftex' is performed  on  `manual',  it  should  *not*  be  removed;  it
provides the ``section index'' used by the on-line help.  You  must  also
keep the `.ind' file; there is no way to re-generate it if it is removed.

                 Testing the ANUPQ package installation
                 --------------------------------------

Now it is time to test the  installation.  After  doing  `configure'  and
`make' you will have a `testPq' script. The script assumes that,  if  the
environment variable `ANUPQ_GAP_EXEC' is set, it is a  correct  path  for
GAP, or otherwise that the `make' call that compiled the `pq' program set
`GAP' to a correct path for GAP (see Section "Running the pq program as a
standalone" in the ANUPQ package manual for more  details).  To  run  the
tests, just type:

  testPq

Some of the tests the script runs take a while. Please be  patient.  Note
that since version 3.0, the ANUPQ package now requires at least  GAP  4.4
and at least version 1.2 of the AutPGrp package (the testPq script checks
for these). The output you see should be something like the following:

  Made dir: /tmp/testPq
  Testing installation of ANUPQ Package (version 3.0)
  
  The first two tests check that the pq C program compiled ok.
  Testing the pq binary ... OK.
  Testing the pq binary's stack size ... OK.
  The pq C program compiled ok! We test it's the right one below.

  The next tests check that you have the right version of GAP
  for version 3.0 of the ANUPQ package and that GAP is finding
  the right versions of the ANUPQ and AutPGrp packages.
  
  Checking GAP ...
   pq binary made with GAP set to: /usr/local/bin/gap
   Starting GAP to determine version and package availability ...
    GAP version (4.4.6) ... OK.
    GAP found ANUPQ package (version 3.0) ... good.
    GAP found pq binary (version 1.8) ... good.
    GAP found AutPGrp package (version 1.2) ... good.
   GAP is OK.

  Checking the link between the pq binary and GAP ... OK.
  Testing the standard presentation part of the pq binary ... OK.
  Doing p-group generation (final GAP/ANUPQ) test ... OK.
  Tests complete.
  Removed dir: /tmp/testPq
  Enjoy using your functional ANUPQ package!

                               Bug reports
                               -----------

If you encounter problems with the `pq' binary, please contact the C code
author: Eamonn O'Brien <obrien@math.auckland.ac.nz>.

If you encounter problems at the GAP level, please  contact  one  of  the
ANUPQ package authors: Greg Gamble <gregg@math.rwth-aachen.de>  or Werner
Nickel <nickel@mathematik.tu-darmstadt.de>.

When sending a bug report, remember we will need to be able to  reproduce
the problem; so please include:

 * The version of GAP you are using; either look at  the  header  when
   you start up GAP, or at the gap> prompt type: VERSION;    or (since 
   GAP 4.4) type: GAPInfo.Version;
 * The operating system you are using e.g. Linux, SunOS 5.8 =  Solaris
   2.8, IRIX 6.5, ...
 * The compiler you used to compile `pq' and  the  options  you  used.
   Type: gcc -v or: cc -version, and  look  in  src/Makefile  for  the
   value of CC to find out.
 * A script, either in GAP or standalone `pq', that  demonstrates  the
   bug, along with a description of why it's a  bug  (e.g.  by  adding
   comments  to  the  script  -  recall,  comments,  both  in  GAP  or
   standalone `pq', begin with a #).

  - Greg Gamble 
    e-mail: gregg@math.rwth-aachen.de)
    www:    http://www.math.rwth-aachen.de/~Greg.Gamble
  -- 9 October, 2001; 18 February, 2002; 16 April, 2002; 
     3 November, 2002; 13 April, 2003; 28 January, 2004;
     20 July, 2005; 28 July, 2005; 24 January, 2006.