chap1.txt

  
  1 Introduction
  
  
  1.1 Overview
  
  The GAP 4 package ANUPQ provides an interface to the ANU pq C progam written
  by  Eamonn  O'Brien,  making the functionality of the C program available to
  GAP.  Henceforth,  we shall refer to the ANUPQ package when referring to the
  GAP interface, and to the ANU pq program or just pq when referring to that C
  program.
  
  The pq program consists of implementations of the following algorithms:
  
  1   A p-quotient algorithm to compute pc-presentations for p-factor groups
        of finitely presented groups.
  
  2   A  p-group generation algorithm to generate pc presentations of groups
        of prime power order.
  
  3   A   standard  presentation  algorithm  used  to  compute  a  canonical
        pc-presentation of a p-group.
  
  4   An  algorithm which can be used to compute the automorphism group of a
        p-group.
  
        This  part  of  the  pq  program  is  not accessible through the ANUPQ
        package.  Instead,  users  are  advised  to consider the GAP 4 package
        AutPGrp  by Bettina Eick and Eamonn O'Brien, which implements a better
        algorithm  in  GAP  for  the  computation  of  automorphism  groups of
        p-groups.
  
  The  current  version of the ANUPQ package requires GAP 4.5, and version 1.5
  of  the  AutPGrp  package.  All  code  that made the package compatible with
  earlier  versions  of  GAP  has  been  removed. If you must use an older GAP
  version  and  cannot upgrade, then you may try using an older ANUPQ version.
  However,  you  should  not use versions of the ANUPQ package older than 2.2,
  since they are known to have bugs.
  
  
  1.2 How to read this manual
  
  It  is  not  expected  that  readers of this manual will read it in a linear
  fashion  from cover to cover; some sections contain material that is far too
  technical to be absorbed on a first reading.
  
  Firstly,   installers   of   the   ANUPQ   package   will   need   to   read
  Chapter 'Installing  the  ANUPQ  Package',  if they have not already gleaned
  these details from the README file.
  
  Once the ANUPQ package is installed, users of the ANUPQ package will benefit
  most  by  first  reading  Chapter 'Mathematical Background and Terminology',
  which gives a brief description of the background and terminology used (this
  chapter  also  cites  a  number  of references for further reading), and the
  introduction  of Chapter 'Infrastructure' (skip the remainder of the chapter
  on a first reading).
  
  Then the user/reader should pursue Chapter 'Non-interactive ANUPQ functions'
  in detail, delving into Chapter 'ANUPQ Options' as necessary for the options
  of  the  functions  that are described. The user will become best acquainted
  with  the  ANUPQ  package by trying the examples. This chapter describes the
  non-interactive functions of the ANUPQ package, i.e. one-shot functions that
  invoke the pq program in such a way that once GAP has got what it needs, the
  pq is allowed to exit. It is expected that most of the time, users will only
  need these functions.
  
  Advanced  users  will  want to explore Chapter 'Interactive ANUPQ functions'
  which  describes  all  the interactive functions of the ANUPQ package; these
  are  functions  that  extract  information  via a dialogue with a running pq
  process. Occasionally, a user needs the next step; the functions provided in
  this  chapter  make  use  of  data  from  previous  steps retained by the pq
  program, thus allowing the user to interact with the pq program like one can
  when  one  uses  the  pq  program  as  a  stand-alone  (see guide.dvi in the
  standalone-doc directory).
  
  After     having    read    Chapters 'Non-interactive    ANUPQ    functions'
  and 'Interactive  ANUPQ  functions',  cross-references  will  have taken the
  reader  into  Chapter 'ANUPQ  Options';  by this stage, the reader need only
  read the introduction of Chapter 'ANUPQ Options'.
  
  After  the  reader  has  developed some facility with the ANUPQ package, she
  should explore the examples described in Appendix 'Examples'.
  
  If  you  run  into  trouble  using the ANUPQ functions, some troubleshooting
  hints  are  given  in  Section 'Hints  and  Warnings  regarding  the  use of
  Options'.  If  the  troubleshooting  hints  don't help, Section 'Authors and
  Acknowledgements'  below,  gives  contact  details  for  the  authors of the
  components of the ANUPQ package.
  
  
  1.3 Authors and Acknowledgements
  
  The  C  implementation  of  the  ANU  pq  standalone was developed by Eamonn
  O'Brien.
  
  An  interactive  interface using iostreams was developed with the assistance
  of Werner Nickel by Greg Gamble.
  
  The  GAP  4  version  of  this package was adapted from the GAP 3 version by
  Werner Nickel.
  
  A new co-maintainer, Max Horn, joined the team in November, 2011.
  
  The   authors   would  like  to  thank  Joachim  Neubüser  for  his  careful
  proof-reading   and   advice,   and  for  formulating  Chapter 'Mathematical
  Background and Terminology'.
  
  We would also like to thank Bettina Eick who by her testing and provision of
  examples  helped  us to eliminate a number of bugs and who provided a number
  of  valuable  suggestions  for  extensions  of  the package beyond the GAP 3
  capabilities.
  
  If  you  find  a  bug,  the  last  section  of  ANUPQ's README describes the
  information  we need and where to send us a bug report; please take the time
  to read this (i.e. help us to help you).