###############################################################################
#
#     Australian National University p-Quotient Program 
#
#     Version 1.2
#
#     April 1994
#
###############################################################################

This implementation was developed in C by 

Eamonn O'Brien 
School of Mathematical Sciences
Australian National University
Canberra, ACT 0200

e-mail obrien@maths.anu.edu.au
Telephone +61-(0)6-249 2963 (office)
FAX +61-(0)6-249 5549 

###############################################################################
#
# Program content 
# 
###############################################################################

The program provides access to implementations of the following algorithms:

1. A p-quotient algorithm to compute a power-commutator presentation
for a p-group.  The algorithm implemented here is based on that 
described in 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 & Havas. The basic data structures of that implementation 
are retained.

The current implementation incorporates the following features:

a. collection from the left (see Vaughan-Lee, 1990); 
   Vaughan-Lee's implementation of this collection 
   algorithm is used in the program;

b. an improved consistency algorithm (see Vaughan-Lee, 1982);

c. new exponent law enforcement and power routines; 

d. closing of relations under the action of automorphisms;

e. some formula evaluation.

For details of these latter improvements, see 
Newman and O'Brien (in preparation). 

2. A p-group generation algorithm to generate descriptions of p-groups. 
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 & 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 (1993).

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


###############################################################################
#
#Access via other programs
#
###############################################################################

Access to parts of this program is provided via Magma, GAP, 
and Quotpic. 

This program is supplied as a package within GAP.
The link from GAP to pq is described in the manual
for GAP 3.2 (and later versions); all of the necessary 
code with documentation can be found in the gap 
directory of this distribution.

###############################################################################
#
#References
#
###############################################################################

George Havas and M.F. Newman (1980), "Application of computers
to questions like those of Burnside", Burnside Groups (Bielefeld, 1977), 
Lecture Notes in Math. 806, pp. 211-230. Springer-Verlag.

M.F. Newman (1977), "Determination of groups of prime-power order", 
Group Theory (Canberra, 1975). Lecture Notes in Math. 573, pp. 73-84. 
Springer-Verlag.

M.F. Newman and E.A. O'Brien (in preparation), "Application of computers to 
questions like those of Burnside II".

E.A. O'Brien (1990), "The p-group generation algorithm",
J. Symbolic Comput. 9, 677-698.

E.A. O'Brien (1993), ``Isomorphism testing for p-groups", 
J. Symbolic Comput. 17 (1).

E.A. O'Brien (1994), ``Computing automorphism groups of p-groups", 
to appear in Proceeding of CANT '92 (Sydney).

M.R. Vaughan-Lee (1982), "An Aspect of the Nilpotent Quotient Algorithm", 
Computational Group Theory (Durham, 1982), pp. 76-83. Academic Press.

Michael Vaughan-Lee (1990), The Restricted Burnside Problem,
London Mathematical Society monographs (New Ser.) #5.
Clarendon Press, New York, Oxford.

M.R. Vaughan-Lee (1990), "Collection from the left", 
J. Symbolic Comput. 9, 725-733.

###############################################################################
#
# Installation procedure 
#
###############################################################################

1. The directory pq contains the following subdirectories:

   bin -- directory for storage of binary file 
   cayley -- a cshell file and a cayley library file 
   doc -- documentation on use of program
   examples -- a number of sample input files for the program
   gap -- GAP library files and documentation on use within GAP
   include  -- C header files 
   isom -- sample input files illustrating canonical presentation computations
   magma -- a cshell file and a Magma library file 
   src -- C source files and a Makefile
   TEST -- some log files + a test program to check correctness
   MakeLibrary -- collection of tools which can be used to generate 
           both CAYLEY and GAP libraries of group collections;
           read the README in that directory for details  

2. The file, guide.tex, in the doc directory is a LaTeX file. 
   It is a basic guide to the use of the p-Quotient Program. 
   It may require some minor modifications before you can 
   print it out.

3. To create the binary --
   a. change to the src directory;
   b. ensure that the conditional compilation flags in the 
      Makefile are set correctly; the -DLARGE_INT flag controls
      the storage and display of automorphism group orders;
      if you want to use this flag, you must have an up-to-date 
      copy of the GNU MP procedures on your machine;
   c. system dependent features are collected in system.c;
      in particular, you may wish to look at the run time function 
      to ensure that the CPU time reported by the program is correct;
   d. type make pq
   e. to remove all of the object files, type make clean

   A binary file, pq, will be placed in the directory bin.

4. The total space requirements for this directory (including 
   the binary but excluding the object files) is about 1.5MB.

5. In p-group generation, if the automorphism group of the 
   starting group is insoluble, then pq calls one of CAYLEY or 
   GAP or Magma to perform particular stabiliser computations 
   (see the User Guide for more details).
   The user of pq may choose which of these systems is to 
   be called --  however, the choice for this link MUST be 
   made by the user at compilation time by setting one of the
   CAYLEY_LINK or GAP_LINK or Magma_LINK flags in the Makefile.
   Points 6, 7, and 8 below discuss each of these links in turn.
   
6. The cayley directory contains a cshell file, CAYLEY_script, and 
   one CAYLEY library file, stabcalc. 
   
   If you plan to use the link from this program to the system CAYLEY, 
   you will need to take the following action:

   a. An environment variable, CAYLEY_DIR, must be set to have as its
      value the path to the directory cayley. If you wish to alter
      the name of this environment variable, edit the occurrence
      of this variable in the src file CAYLEY.c, its occurrence
      in CAYLEY_script, and remake the binary.

   b. The cshell file, CAYLEY_script, executes CAYLEY. 
      The binary for CAYLEY must be in your path.

   The "egrep -v" commands in the CAYLEY_script file are used to
   remove certain output which occurs in the CAYLEY log file.
   In order that the CAYLEY_output file is processed correctly
   by pq, it is necessary that no text occurs before the listing 
   of two integers and the generators of the stabiliser. 
   On certain machines, the output file CAYLEY_output may contain 
   other junk before these entries -- if such is the case on your 
   machine, you will need to add additional "egrep -v" command to 
   remove such material.

7. The instructions which you must follow in order to use
   the Magma link are similar to those described under 6. -- 
   except all occurrences of CAYLEY are replaced by Magma.

8. The link from pq to GAP assumes that you use GAP 3.2
   (or a later release) *with* the *anupq package* installed.

   The supplied program does not work with *earlier* versions
   of GAP and should not be used with them.

   If the binary for GAP 3.2 (or later) is called gap and is in your 
   default path, you need do no more; if it is not in your path, 
   you must set an environment variable ANUPQ_EXEC_GAP to 
   point to the GAP executable.

9. The TEST directory contains a number of log files, with
   extension .orig, together with a cshell file called TEST.
   This test program runs through a number of the examples 
   in the examples directory and compares the results generated with 
   those listed in the .orig files of this directory. If the 
   p-quotient program is running correctly, the TEST program 
   should report only differences in the date, name of machines 
   and times taken. If there are other significant differences, 
   please report.
   
   Execute the test program by typing TEST 
   (If your pq directory structure is different, you may need to alter 
    the relative paths in TEST for both binary and command files.)

   The total time taken for the test on a SPARCstation 10/51 is
   about 30 seconds of user time.

10. See the documentation for information on run-time parameters.

11. Please report bugs/problems/feedback to obrien@maths.anu.edu.au

