# ANUPQ

ANU p-Quotient

Version 3.2.1
Released 2019-04-18

This project is maintained by Greg Gamble, Max Horn

                            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.

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. In particular
it is known to work on Linux and Mac OS X, and also on Windows equipped
with cygwin.

You can download anupq-XXX.tar.gz' (where XXX' is the  package  version

https://gap-packages.github.io/anupq/

or via the GAP web site

https://www.gap-system.org/Packages/anupq.html

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

To install the ANUPQ package, move the file anupq-.tar.gz' 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.)

ANUPQ package requires at least GAP 4.8 and AutPGrp 1.5, although we
supports using GMP for large integer support.

Unpack the archive anupq-.tar.gz' in the pkg' directory.

Change directory to the newly created anupq' directory. Now you need to
call configure'. If you installed ANUPQ into the main pkg' directory,
simply do this:

./configure

If you installed ANUPQ in another directory than the usual 'pkg'
subdirectory, do

./configure --with-gaproot=path

where 'path' is a path to the GAP home directory. See

./configure --help

for further options.

Afterwards, you can simply call

make

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

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/')  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).

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

The ANUPQ package documentation source files, now XML  (for GAPDoc),  are
found in the doc' directory. There you should also find manual.pdf',  a
PDF version of the manual,  and  various  HTML files constituting the HTML
version of the manual (actually there are two HTML versions of the manual,
the  one with _mj' files have MathJax  enabled).  The  initial  page  for
the HTML version of the manual is chap0.html'  (or  chap0_mj.html'  with
MathJax enabled), but you can toggle between the versions,  once you  have
opened either, with your favourite browser.

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.
The output you see should be something like the following:

Testing installation of ANUPQ Package (version 3.2.1)

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.1 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.10.1) ... OK.
GAP found ANUPQ package (version 3.2.1) ... good.
GAP found pq binary (version 1.9) ... good.
GAP found AutPGrp package (version 1.5) ... 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
-----------

For bug reports, feature requests and suggestions, please refer to

https://github.com/gap-packages/anupq/issues

When sending a bug report, remember we will need to be able to  reproduce
* The compiler you used to compile pq' and  the  options  you  used.
standalone pq', begin with a #).