%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%A  share.tex                   GAP documentation                Frank Celler
%%
%A  @(#)$Id: share.tex,v 3.32 1994/07/07 11:07:18 mschoene Rel $
%%
%Y  Copyright 1990-1992,  Lehrstuhl D fuer Mathematik,  RWTH Aachen,  Germany
%%
%H  $Log: share.tex,v $
%H  Revision 3.32  1994/07/07  11:07:18  mschoene
%H  changed introduction for GRAPE to avoid two overfull hboxes
%H
%H  Revision 3.31  1994/07/01  08:24:40  fceller
%H  updated GRAPE to 2.2
%H
%H  Revision 3.30  1994/06/20  14:46:12  vfelsch
%H  corrected xgap example
%H
%H  Revision 3.29  1994/06/17  19:03:58  vfelsch
%H  examples adjusted to version 3.4
%H
%H  Revision 3.28  1994/06/03  08:57:20  mschoene
%H  changed a few things to avoid LaTeX warnings
%H
%H  Revision 3.27  1994/05/31  11:37:51  vfelsch
%H  updated introduction
%H
%H  Revision 3.26  1994/05/22  12:41:04  fceller
%H  added smash package
%H
%H  Revision 3.25  1994/05/19  13:43:36  sam
%H  bug fixes
%H
%H  Revision 3.23  1994/05/10  16:00:36  sam
%H  changes in section about VE installation
%H
%H  Revision 3.22  1994/04/28  10:16:34  fceller
%H  added Alice's SQ
%H
%H  Revision 3.21  1994/04/27  08:59:33  fceller
%H  chnaged ANU PQ section (srce is now src)
%H
%H  Revision 3.20  1994/04/12  14:14:35  sam
%H  added section about the VE package
%H
%H  Revision 3.19  1994/03/23  09:39:21  fceller
%H  changed "srce" to "src" in PQ section
%H
%H  Revision 3.18  1993/11/09  00:08:10  martin
%H  fixed references to installation sections
%H
%H  Revision 3.17  1993/10/21  17:15:24  fceller
%H  added xgap and sisyphos
%H
%H  Revision 3.16  1993/10/20  12:25:58  fceller
%H  distribution is now done using zoo archives not tar archives
%H
%H  Revision 3.15  1993/07/27  08:21:28  fceller
%H  clearified example in 'RequirePackage'
%H
%H  Revision 3.14  1993/07/20  11:07:11  fceller
%H  updated GRAPE section
%H
%H  Revision 3.13  93/06/28  10:01:52  fceller
%H  new ANU pq version
%H
%H  Revision 3.12  1993/05/28  13:37:26  gap
%H  added GRAPE
%H
%H  Revision 3.11  1993/02/19  10:48:42  gap
%H  adjustments in line length and spelling
%H
%H  Revision 3.10  1993/02/18  09:50:38  felsch
%H  examples fixed
%H
%H  Revision 3.9  1993/02/01  11:36:55  fceller
%H  added reference to "weyl.tex" and "anupq.tex"
%H
%H  Revision 3.8  1993/01/25  22:16:09  fceller
%H  added Werner's NQ
%H
%H  Revision 3.7  1993/01/05  11:41:05  fceller
%H  added ANU pq in the introduction
%H
%H  Revision 3.6  1993/01/04  11:01:25  fceller
%H  fixed some misspellings
%H
%H  Revision 3.5  1992/12/29  15:56:35  fceller
%H  add the ANU pq
%H
%H  Revision 3.4  1992/12/04  11:11:58  fceller
%H  added Neubueser's introduction
%H
%H  Revision 3.3  1992/12/02  10:08:45  fceller
%H  fixed a few bad text alignments
%H
%H  Revision 3.2  92/11/30  15:17:32  fceller
%H  initial GAP 3.2 revision
%%
\def\fuer{f{\accent127 u}r}
\def\GRAPE{\sf GRAPE}
\def\MeatAxe{\sf MeatAxe}
\def\SISYPHOS{\sc SISYPHOS}
\def\VE{Vector Enumeration}
\def\nauty{\it nauty}
\Chapter{Share Libraries}

Contributions from  people working at Lehrstuhl D,  RWTH  Aachen, or  any
other place can become available in {\GAP} in two different ways\:

1.  They can become parts of the main {\GAP} library of functions.  Their
origin will then be rather carefully documented in the respective program
files, but  will  not occur in the  description of these functions in the
manual.   This is  e.g.   the  case  -- to mention just one of many  such
contributions  --  with  programs  for  finding  composition  factors  of
permutation groups, written by Akos Seress. The reason for  this decision
about  keeping track  of the  origin of such  contributions is that quite
often such  functions  in  the  main  {\GAP} library  have a  complicated
history with changes and contributions from various people.

2.   On the other  hand  there are  packages  written  by one or  several
persons for specific purposes either in the {\GAP}  language or even in C
which  are  made  available en  block   in {\GAP}.   Such   packages will
constitute *share libraries*.  A  share library will  stay under the full
responsibility of  its author(s), which will  be  named in the respective
chapter in the manual,  they will in  particular  keep the  copyright for
this package, and they  will also have to  provide the documentation  for
it.  However  provisions  will be made  to call  the functions of  such a
package  like any other  {\GAP} functions, and  to call the documentation
via help functions like any other part of the {\GAP} documentation.  Also
these packages will automatically be made available with the main body of
{\GAP} through ftp and will be sent together with the main body of {\GAP}
in case we have to fulfill a request  to send {\GAP} to institutions that
cannot obtain {\GAP} via electronic networks.

The inclusion of packages as  {\GAP} share libraries should be negotiated
with Lehrstuhl D \fuer\ Mathematik, RWTH Aachen, for certain standards of
the documentation and program organisation that should be met in order to
facilitate  the  use of the   packages in the  context  of {\GAP} without
problems. A necessary condition for any  package to become a {\GAP} share
library is that it is  made available under  the conditions formulated in
the {\GAP} copyright statement, in particular free  of any charge, except
for refund of expenses for sending, if such occur.

The  first section  describes how to load  a  share  library package (see
"RequirePackage").

The next sections describe the ANU pq package and how to install  it (see
"ANU pq Package" and "Installing the ANU pq Package").

The next sections describe the ANU Sq package and how to install  it (see
"ANU Sq Package" and "Installing the ANU Sq Package").

The next  sections describe the {\GRAPE} package and  how to  install  it
(see "GRAPE Package" and "Installing the GRAPE Package").

The next  sections describe the {\MeatAxe} package and  how to install it
(see "MeatAxe Package" and "Installing the MeatAxe Package").

The next sections describe the NQ package  and how to install it (see "NQ
Package" and "Installing the NQ Package").

The next sections describe  the {\SISYPHOS} package and how to install it
(see "SISYPHOS Package" and "Installing the SISYPHOS Package").

The next sections describe the  smash package and  how to install it (see
"Smash Package" and "Installing the Smash Package").

The next sections describe the {\VE} package and  how to install  it (see
"Vector Enumeration Package" and "Installing the Vector Enumeration
Package").

The next sections describe the  Weyl package and  how to install  it (see
"Weyl Package" and "Installing the Weyl Package").

The  last sections describe the experimental  X-Windows interface and how
to install   it  (see  "The  XGap  Package"   and  "Installing   the XGap
Package").

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{RequirePackage}

'RequirePackage( <name> )'

'RequirePackage' will try to initialize the  share library <name>. If the
package <name> is not installed at your site 'RequirePackage' will signal
an  error.  If the package <name> is already initialized 'RequirePackage'
simply returns without any further actions.

|    gap> CartanMat( "A", 4 );
    Error, Variable: 'CartanMat' must have a value
    gap> ?Cartan
        'CartanMat( <type>, <n> )'

        returns the Cartan matrix of Dynkin type <type> and rank <n>.

            gap> CartanMat( "F", 4 );
            [ [  2, -1,  0,  0 ],
              [ -1,  2, -1,  0 ],
              [  0, -2,  2, -1 ],
              [  0,  0, -1,  2 ] ]

        This function requires the package  "weyl"  (see "RequirePackage").

    # on some system <name> is case-sensitive, so watch out for typos
    gap> RequirePackage( "Weyl" );
    Error, share library "Weyl" is not installed
    gap> RequirePackage( "weyl" );
    gap> CartanMat( "A", 4 );;
    gap> PrintArray( last );
    [ [   2,  -1,   0,   0 ],
      [  -1,   2,  -1,   0 ],
      [   0,  -1,   2,  -1 ],
      [   0,   0,  -1,   2 ] ]|


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{ANU pq Package}

The   ANU  pq  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 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 (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).

The following section describes the installation of the ANU pq package, a
description of the functions available in the  ANU pq package is given in
chapter "ANU Pq".

A reader interested  in details  of the  algorithms  and explanations  of
terms  used  is  referred  to  \cite{HN80},  \cite{OBr90},  \cite{OBr93},
\cite{OBr94},    \cite{New77},    \cite{Vau84},     \cite{Vau90a},    and
\cite{Vau90b}.

For  details about  the implementation and the standalone version see the
README. 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

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installing the ANU pq Package}

The ANU  pq is written  in C and the  package can only be installed under
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, and SUNs running SunOS.

If you got  a complete binary  and source distribution for your  machine,
nothing has   to be done if  you  want to use   the ANU  pq for  a single
architecture. If  you want to use the  ANU pq for machines with different
architectures skip  the extraction and compilation  part of  this section
and proceed with the creation of shell scripts described below.

If you  got a complete source distribution,  skip the  extraction part of
this section and proceed with the compilation part below.

In the example we will assume that you, as user 'gap', are installing the
ANU pq package for use by several users on a network  of two DECstations,
called 'bert' and 'tiffy', and a NeXTstation,  called 'bjerun'. We assume
that  {\GAP}  is   also  installed  on   these  machines   following  the
instructions given in "Installation of GAP for UNIX".

Note that certain parts  of  the  output  in the examples should  only be
taken as rough outline, especially file sizes and file dates are *not* to
be taken literally.

First of  all you have to  get the file  'anupq.zoo' (see "Getting GAP").
Then you  must locate the {\GAP} directory  containing 'lib/' and 'doc/',
this is usually  'gap3r4p0' where '0'  is to be  replaced by  the current
patch level.

|    gap@tiffy:~ > ls -l
    drwxr-xr-x  11 gap     1024 Nov  8  1991 gap3r4p0
    -rw-r--r--   1 gap   360891 Dec 27 15:16 anupq.zoo
    gap@tiffy:~ > ls -l gap3r4p0
    drwxr-xr-x   2 gap     3072 Nov 26 11:53 doc
    drwxr-xr-x   2 gap     1024 Nov  8  1991 grp
    drwxr-xr-x   2 gap     2048 Nov 26 09:42 lib
    drwxr-xr-x   2 gap     2048 Nov 26 09:42 pkg
    drwxr-xr-x   2 gap     2048 Nov 26 09:42 src
    drwxr-xr-x   2 gap     1024 Nov 26 09:42 tst|

Unpack the package using 'unzoo'  (see "Installation  of GAP for  UNIX").
Note that  you must be in the  directory containing 'gap3r4p0'  to unpack
the files.    After you have  unpacked   the source  you may  remove  the
*archive-file*.

|    gap@tiffy:~ > unzoo x anupq
    gap@tiffy:~ > cd gap3r4p0/pkg/anupq
    gap@tiffy:../anupq> ls -l
    drwxr-xr-x  5 gap       512 Feb 24 11:17 MakeLibrary
    -rw-r--r--  1 gap     28926 Jun  8 14:21 Makefile
    -rw-r--r--  1 gap      8818 Jun  8 14:21 README
    -rw-r--r--  1 gap       753 Jun 23 18:59 StandardPres
    drwxr-xr-x  2 gap      1024 Jun  8 14:15 TEST
    drwxr-xr-x  2 gap       512 Jun 16 16:03 bin
    drwxr-xr-x  2 gap       512 May 16 06:58 cayley
    drwxr-xr-x  2 gap       512 Jun  8 08:48 doc
    drwxr-xr-x  2 gap      1024 Mar  5 04:01 examples
    drwxr-xr-x  2 gap       512 Jun 23 16:37 gap
    drwxr-xr-x  2 gap       512 Jun 24 10:51 include
    -rw-rw-rw-  1 gap       867 Jun  9 16:12 init.g
    drwxr-xr-x  2 gap      1024 May 21 02:28 isom
    drwxr-xr-x  2 gap       512 May 16 07:58 magma
    drwxr-xr-x  2 gap      6656 Jun 24 11:10 src |

Typing 'make' will produce a list of possible target.

|    gap@tiffy:../anupq > make
    usage: 'make <target> EXT=<ext>'  where <target> is one of
    'dec-mips-ultrix-gcc2-gmp' for DECstations under Ultrix with gcc/gmp
    'dec-mips-ultrix-cc-gmp'   for DECstations under Ultrix with cc/gmp
    'dec-mips-ultrix-gcc2'     for DECstations under Ultrix with gcc
    'dec-mips-ultrix-cc'       for DECstations under Ultrix with cc
    'hp-hppa1.1-hpux-cc-gmp'   for HP 9000/700 under HP-UX with cc/gmp
    'hp-hppa1.1-hpux-cc'       for HP 9000/700 under HP-UX with cc
    'hp-hppa1.0-hpux-cc-gmp'   for HP 9000/800 under HP-UX with cc/gmp
    'hp-hppa1.0-hpux-cc'       for HP 9000/800 under HP-UX with cc
    'ibm-i386-386bsd-gcc2-gmp' for IBM PCs under 386BSD with gcc/gmp
    'ibm-i386-386bsd-cc-gmp'   for IBM PCs under 386BSD with cc/gmp
    'ibm-i386-386bsd-gcc2'     for IBM PCs under 386BSD with gcc2
    'ibm-i386-386bsd-cc'       for IBM PCs under 386BSD with cc
    'mips-mips-bsd-cc-gmp'     for MIPS under RISC/os Berkeley with cc/gmp
    'mips-mips-bsd-cc'         for MIPS under RISC/os Berkeley with cc
    'next-m68k-mach-gcc2-gmp'  for NeXT under Mach with gcc/gmp
    'next-m68k-mach-cc-gmp'    for NeXT under Mach with cc/gmp
    'next-m68k-mach-gcc2'      for NeXT under Mach with gcc
    'next-m68k-mach-cc'        for NeXT under Mach with cc
    'sun-sparc-sunos-gcc2-gmp' for SUN 4 under SunOs with gcc/gmp
    'sun-sparc-sunos-cc-gmp'   for SUN 4 under SunOs with cc/gmp
    'sun-sparc-sunos-gcc2'     for SUN 4 under SunOs with gcc2
    'sun-sparc-sunos-cc'       for SUN 4 under SunOs with cc
    'unix-gmp'                 for a generic unix system with cc/gmp
    'unix'                     for a generic unix system with cc
    'clean'                    remove all created files

       where <ext> should be a sensible extension, i.e.,
       'EXT=-sun-sparc-sunos' for SUN 4 or 'EXT=' if the PQ only
       runs on a single architecture

       targets are listed according to preference,
       i.e., 'sun-sparc-sunos-gcc2' is better than 'sun-sparc-sunos-cc'.
       additional C compiler and linker flags can be passed with
       'make <target> COPTS=<compiler-opts> LOPTS=<linker-opts>',
       i.e., 'make sun-sparc-sunos-cc COPTS=-g LOPTS=-g'.

       set GAP if gap 3.4 is not started with the command 'gap',
       i.e., 'make sun-sparc-sunos-cc GAP=/home/gap/bin/gap-3.4'.

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

Select the  target you need.  If  you  have the *GNU*  multiple precision
arithmetic (gmp)  installed on your  system, select the target  ending in
'-gmp'. Note that  the  gmp is  *not  required*.   In our  case we  first
compile   the DECstation version.   We assume  that  the command to start
{\GAP}    is  '/usr/local/bin/gap'   for   'tiffy'    and  'bjerun'   and
'/rem/tiffy/usr/local/bin/gap' for 'bert'.

|    gap@tiffy:../anupq > make dec-mips-ultric-cc \
                               GAP=/usr/local/bin/gap \
			       EXT=-dec-mips-ultrix
    # you will see a lot of messages and a few warnings |

Now repeat the compilation  for the NeXTstation. *Do not* forget to clean
up.

|    gap@tiffy:../anupq > rlogin bjerun
    gap@bjerun:~ > cd gap3r4p0/pkg/anupq
    gap@bjerun:../anupq > make clean
    gap@bjerun:../src > make next-m68k-mach-cc \
                             GAP=/usr/local/bin/gap \
			     EXT=-next-m68k-mach
    # you will see a lot of messages and a few warnings
    gap@bjerun:../anupq > exit
    gap@tiffy:../anupq > |

Switch into the subdirectory 'bin/'  and create a  script which will call
the correct binary for each machine. A skeleton  shell script is provided
in 'bin/pq.sh'.

|    gap@tiffy:../anupq > cd bin
    gap@tiffy:../bin > cat > pq
    |\#|!/bin/csh
    switch ( `hostname` )
      case 'tiffy':
        exec $0-dec-mips-ultrix $* ;
        breaksw ;
      case 'bert':
        setenv ANUPQ_GAP_EXEC /rem/tiffy/usr/local/bin/gap ;
        exec $0-dec-mips-ultrix $* ;
        breaksw ;
      case 'bjerun':
        limit stacksize 2048 ;
        exec $0-next-m68k-mach $* ;
        breaksw ;
      default:
        echo "pq: sorry, no executable exists for this machine" ;
        breaksw ;
    endsw
    |<ctr>-'D'|
    gap@tiffy:../bin > chmod 755 pq
    gap@tiffy:../bin > cd .. |

Note that the  NeXTstation requires you to raise the stacksize.   If your
default limit on any other machine for the stack size  is less than  1024
you might need to add the 'limit stacksize 2048' line.

If the documentation is  not  already installed  or an older  version  is
installed, copy  the file 'gap/anupq.tex' into  the  'doc/' directory and
run latex  again (see "Installation  of  GAP for  UNIX").  In general the
documentation will   already  be installed  so  you   can  just skip  the
following step.

|    gap@tiffy:../anupq > cp gap/anupq.tex ../../doc
    gap@tiffy:../anupq > cd ../../doc
    gap@tiffy:../doc > latex manual
    # a few messages about undefined references
    gap@tiffy:../doc > latex manual
    # a few messages about undefined references
    gap@tiffy:../doc > makeindex manual
    # 'makeindex' prints some diagnostic output
    gap@tiffy:../doc > latex manual
    # there should be no warnings this time
    gap@tiffy:../doc cd ../pkg/anupq |

Now it is time to test  the installation.  The  first test will only test
the ANU pq.

|    gap@tiffy:../anupq > bin/pq < gap/test1.pga
    # a lot of messages ending in
    **************************************************
    Starting group: c3c3 |\#|2;2 |\#|4;3
    Order: 3^7
    Nuclear rank: 3
    3-multiplicator rank: 4
    |\#| of immediate descendants of order 3^8 is 7
    |\#| of capable immediate descendants is 5

    **************************************************
    34 capable groups saved on file c3c3_class4
    Construction of descendants took 1.92 seconds

    Select option: 0
    Exiting from p-group generation

    Select option: 0
    Exiting from ANU p-Quotient Program
    Total user time in seconds is 1.97
    gap@tiffy:../anupq > ls -l c3c3*
    total 89
    -rw-r--r--    1 gap    3320 Jun 24 11:24 c3c3_class2
    -rw-r--r--    1 gap    5912 Jun 24 11:24 c3c3_class3
    -rw-r--r--    1 gap   56184 Jun 24 11:24 c3c3_class4
    gap:../anupq > rm c3c3_class* |

The second test will test the stacksize. If it is too small you will  get
a memory fault, try to raise the stacksize as described above.

|    gap@tiffy:../anupq > bin/pq < gap/test2.pga
    # a lot of messages ending in
    **************************************************
    Starting group: c2c2 |\#|1;1 |\#|1;1 |\#|1;1
    Order: 2^5
    Nuclear rank: 1
    2-multiplicator rank: 3
    Group c2c2 |\#|1;1 |\#|1;1 |\#|1;1 is an invalid starting group

    **************************************************
    Starting group: c2c2 |\#|2;1 |\#|1;1 |\#|1;1
    Order: 2^5
    Nuclear rank: 1
    2-multiplicator rank: 3
    Group c2c2 |\#|2;1 |\#|1;1 |\#|1;1 is an invalid starting group
    Construction of descendants took 0.47 seconds

    Select option: 0
    Exiting from p-group generation

    Select option: 0
    Exiting from ANU p-Quotient Program
    Total user time in seconds is 0.50
    gap@tiffy:../anupq > ls -l c2c2*
    total 45
    -rw-r--r--    1 gap   6228 Jun 24 11:25 c2c2_class2
    -rw-r--r--    1 gap  11156 Jun 24 11:25 c2c2_class3
    -rw-r--r--    1 gap   2248 Jun 24 11:25 c2c2_class4
    -rw-r--r--    1 gap      0 Jun 24 11:25 c2c2_class5
    gap:../anupq > rm c2c2_class* |

The third example tests the link between the ANU pq and {\GAP}.  If there
is a problem you will get a error message saying
'Error in  system  call  to GAP';  if this happens, check the environment
variable 'ANUPQ\_GAP\_EXEC'.

|    gap@tiffy:../anupq > bin/pq < gap/test3.pga
    # a lot of messages ending in
    **************************************************
    Starting group: c5c5 |\#|1;1 |\#|1;1
    Order: 5^4
    Nuclear rank: 1
    5-multiplicator rank: 2
    |\#| of immediate descendants of order 5^5 is 2

    **************************************************
    Starting group: c5c5 |\#|1;1 |\#|2;2
    Order: 5^5
    Nuclear rank: 3
    5-multiplicator rank: 3
    |\#| of immediate descendants of order 5^6 is 3
    |\#| of immediate descendants of order 5^7 is 3
    |\#| of capable immediate descendants is 1
    |\#| of immediate descendants of order 5^8 is 1
    |\#| of capable immediate descendants is 1

    **************************************************
    2 capable groups saved on file c5c5_class4

    **************************************************
    Starting group: c5c5 |\#|1;1 |\#|2;2 |\#|4;2
    Order: 5^7
    Nuclear rank: 1
    5-multiplicator rank: 2
    |\#| of immediate descendants of order 5^8 is 2
    |\#| of capable immediate descendants is 2

    **************************************************
    Starting group: c5c5 |\#|1;1 |\#|2;2 |\#|7;3
    Order: 5^8
    Nuclear rank: 2
    |\#| of immediate descendants of order 5^9 is 1
    |\#| of capable immediate descendants is 1
    |\#| of immediate descendants of order 5^10 is 1
    |\#| of capable immediate descendants is 1

    **************************************************
    4 capable groups saved on file c5c5_class5
    Construction of descendants took 0.62 seconds

    Select option: 0
    Exiting from p-group generation

    Select option: 0
    Exiting from ANU p-Quotient Program
    Total user time in seconds is 0.68
    gap@tiffy:../anupq > ls -l c5c5*
    total 41
    -rw-r--r--    1 gap     924 Jun 24 11:27 c5c5_class2
    -rw-r--r--    1 gap    2220 Jun 24 11:28 c5c5_class3
    -rw-r--r--    1 gap    3192 Jun 24 11:30 c5c5_class4
    -rw-r--r--    1 gap    7476 Jun 24 11:32 c5c5_class5
    gap:../anupq > rm c5c5_class* |

The fourth test will test the standard presentation part of the pq.

|    gap@tiffy:../anupq > bin/pq -i -k < gap/test4.sp
    # a lot of messages ending in
    Computing standard presentation for class 9 took 0.43 seconds
    The largest 5-quotient of the group has class 9

    Select option: 0
    Exiting from ANU p-Quotient Program
    Total user time in seconds is 2.17
    gap@tiffy:../anupq > ls -l SPRES
    -rw-r--r--  1 gap     768 Jun 24 11:33 SPRES
    gap@tiffy:../anupq > diff SPRES gap/out4.sp
    # there should be no difference if compiled with '-gmp'
    156250000
    gap@tiffy:../anupq > rm SPRES |

The last  test  will test the  link  between {\GAP} and   the ANU pq.  If
everything goes well you should not see any message.

|    gap@tiffy:../anupq > gap -b
    gap> RequirePackage( "anupq" );
    gap> ReadTest( "gap/anupga.tst" );
    gap> |

You may now repeat the tests for the other machines.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{ANU Sq Package}
\index{Sq}

'Sq( <G>, <L> )'

The function  'Sq' is  the  interface to the  Soluble Quotient standalone
program.

Let <G> be  a finitely presented group  and let <L> be  a list  of lists.
Each of these lists is a list of integer pairs [$p_i$,$c_i$], where $p_i$
is  a prime and  $c_i$ is a  non-negative integer and $p_i \not= p_{i+1}$
and $c_i$ positive for  $i \< k$.   'Sq' computes a  consistent
power conjugate   presentation  for a  finite  soluble group  given  as a
quotient of the finitely presented group <G> which is described by <L> as
follows.

Let  $H$ be a  group and  $p$ a  prime.  The  series  $$H = {P}^p_0(H)\ge
{P}^p_1(H)\ge\cdots\,\,\hbox  to  1.5   cm{\hfil  with\ }    {P}^p_i(H) =
[{P}^p_{i-1}(H),H] \left({P}^p_{i-1} (H)\right)^p$$ for $i  \ge 1$ is the
{\it lower exponent-$p$ central series} of $H.$

For $1 \le i \le k$ and $0 \le j \le  c_i$ define the list ${\rm L}_{i,j}
=   [(p_1,c_1),\ldots,  (p_{i-1},c_{i-1}),(p_{i}, j)    ].$ Define  ${\rm
L}_{1,0}(G) = G.$ For $1  \le i \le  k$ and $1  \le j \le c_i$ define the
subgroups  $${\rm L}_{i,j}(G) =  {\rm  P}_{j}^{p_i}( {\rm L}_{i,0}(G) )$$
and for $1  \le i \< k$ define the  subgroups $${\rm L}_{i+1,0}(G) = {\rm
L}_{i,c_i}(G)$$ and ${\rm L}(G)  = {\rm  L}_{k,c_k}(G).$ Note that  ${\rm
L}_{i,j}(G) \ge {\rm L}_{i,j+1}(G)$ holds for $j \< c_i$.

The chain of subgroups $$G  = {\rm L}_{1,0}(G)  \ge {\rm L}_{1,1}(G)  \ge
\cdots  \ge {\rm L}_{1,c_1}(G)    = {\rm L}_{2,0}(G)\ge \cdots   \ge {\rm
L}_{k,c_k}(G) = {\rm  L}(G)  $$   is   called  the  {\it  soluble   ${\rm
L}$-series} of $G.$

'Sq' computes  a  consistent  power  conjugate  presentation for  $G/{\rm
L}(G),$ where  the   presentation exhibits a  composition  series  of the
quotient group which is a refinement of the soluble ${\rm L}$-series.  An
epimorphism from $G$ onto $G/{\rm L}(G)$ is listed in comments.

The algorithm proceeds by computing power conjugate presentations for the
quotients  $G/{\rm L}_{i,j}(G)$ in   turn.   Without loss of   generality
assume that a  power conjugate presentation  for $G/{\rm L}_{i,j}(G)$ has
been computed  for $j \< c_i.$ The basic step computes a  power conjugate
presentation for $G/{\rm L}_{i,j+1}(G).$ The group ${\rm L}_{i,j}(G)/{\rm
L}_{i,j+1}(G)$  is  a  $p_{i}$-group.   If  during  the  basic step it is
discovered that ${\rm  L}_{i,j}(G)   = {\rm L}_{i,j+1}(G),$  then   ${\rm
L}_{i+1,0}(G)$ is set to ${\rm L}_{i,j}(G).$

Note that during the basic step the vector enumerator is called.

|    gap> RequirePackage("anusq");
    gap> f := FreeGroup( "a", "b" );;
    gap> f := f/[ (f.1*f.2)^2*f.2^-6, f.1^4*f.2^-1*f.1*f.2^-9*f.1^-1*f.2 ];
    Group( a, b )
    gap> g := Sq( f, [[2,1],[3,1],[2,2],[3,2]] );
    rec(
      generators := [ a.1, a.2, a.3, a.4, a.5, a.6, a.7, a.8 ],
      relators :=
       [ a.1^2*a.3^-1, a.1^-1*a.2*a.1*a.4^-1*a.2^-2, a.2^3*a.5^-1,
          a.1^-1*a.3*a.1*a.3^-1,
          a.2^-1*a.3*a.2*a.6^-1*a.5^-1*a.4^-1*a.3^-1, a.3^2*a.7^-1*a.5^-1,
          a.1^-1*a.4*a.1*a.7^-1*a.4^-1*a.3^-1,
          a.2^-1*a.4*a.2*a.8^-1*a.7^-1*a.6^-2*a.3^-1,
          a.3^-1*a.4*a.3*a.8^-2*a.7^-2*a.5^-1*a.4^-1,
          a.4^2*a.8^-2*a.7^-2*a.6^-2*a.5^-1,
          a.1^-1*a.5*a.1*a.8^-1*a.7^-1*a.6^-1*a.5^-1,
          a.2^-1*a.5*a.2*a.5^-1, a.3^-1*a.5*a.3*a.8^-2*a.6^-1*a.5^-1,
          a.4^-1*a.5*a.4*a.7^-1*a.5^-1, a.5^2,
          a.1^-1*a.6*a.1*a.8^-1*a.7^-2*a.6^-1,
          a.2^-1*a.6*a.2*a.8^-2*a.6^-2,
          a.3^-1*a.6*a.3*a.8^-2*a.7^-2*a.6^-2,
          a.4^-1*a.6*a.4*a.8^-1*a.7^-2, a.5^-1*a.6*a.5*a.8^-2*a.6^-2,
          a.6^3, a.1^-1*a.7*a.1*a.6^-2, a.2^-1*a.7*a.2*a.7^-2*a.6^-2,
          a.3^-1*a.7*a.3*a.8^-1*a.7^-1*a.6^-2, a.4^-1*a.7*a.4*a.6^-1,
          a.5^-1*a.7*a.5*a.7^-2, a.6^-1*a.7*a.6*a.8^-1*a.7^-1, a.7^3,
          a.1^-1*a.8*a.1*a.8^-2, a.2^-1*a.8*a.2*a.8^-1,
          a.3^-1*a.8*a.3*a.8^-1, a.4^-1*a.8*a.4*a.8^-1,
          a.5^-1*a.8*a.5*a.8^-1, a.6^-1*a.8*a.6*a.8^-1,
          a.7^-1*a.8*a.7*a.8^-1, a.8^3 ] ) |

This implementation was developed in C by

Alice C. Niemeyer \\
Department of Mathematics \\
University of Western Australia \\
Nedlands, WA 6009 \\
Australia

email: alice@maths.uwa.edu.au

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installing the ANU Sq Package}

The ANU Sq  is written in C  and the package  can only be installed under
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 PC running
NnetBSD 0.9, and SUNs running SunOS.

It requires Steve Linton\'s vector enumerator (either as standalone or as
GAP share  library). Make sure  that   it is installed before   trying to
install the ANU Sq.

If you have a complete binary and  source distribution  for your machine,
nothing has  to  be done if  you want  to use the   ANU Sq  for  a single
architecture. If you want to use  the ANU Sq  for machines with different
architectures skip  the extraction and compilation  part  of this section
and proceed with the creation of shell scripts described below.

If you have a complete source distribution,  skip the  extraction part of
this section and proceed with the compilation part below.

In the example we will assume that you, as user 'gap', are installing the
ANU Sq package for use by several users  on a network of two DECstations,
called   'bert' and  'tiffy',   and a  Sun   running  SunOS  5.3,  called
'galois'. We  assume  that {\GAP}  is also   installed on these  machines
following the instructions given in "Installation of GAP for UNIX".

Note that certain parts  of  the  output  in the examples should  only be
taken as rough outline, especially file sizes and file dates are *not* to
be taken literally.

First of  all you have to  get the file  'anusq.zoo' (see "Getting GAP").
Then you  must locate the {\GAP} directory  containing 'lib/' and 'doc/',
this is usually  'gap3r4p0' where '0'  is to be  replaced by  the current
patch level.

|    gap@tiffy:~ > ls -l
    drwxr-xr-x  11 gap     1024 Nov  8  1991 gap3r4p0
    -rw-r--r--   1 gap   360891 Dec 27 15:16 anusq.zoo
    gap@tiffy:~ > ls -l gap3r4p0
    drwxr-xr-x   2 gap     3072 Nov 26 11:53 doc
    drwxr-xr-x   2 gap     1024 Nov  8  1991 grp
    drwxr-xr-x   2 gap     2048 Nov 26 09:42 lib
    drwxr-xr-x   2 gap     2048 Nov 26 09:42 pkg
    drwxr-xr-x   2 gap     2048 Nov 26 09:42 src
    drwxr-xr-x   2 gap     1024 Nov 26 09:42 tst|

Unpack the package using 'unzoo'  (see "Installation  of GAP for  UNIX").
Note that  you must be in the  directory containing 'gap3r4p0'  to unpack
the files.    After you have  unpacked   the source  you may  remove  the
*archive-file*.

|    gap@tiffy:~ > unzoo x anusq
    gap@tiffy:~ > cd gap3r4p0/pkg/anusq
    gap@tiffy:../anusq> ls -l
    -rw-r--r--   1 gap     5232 Apr 10 12:40 Makefile
    -rw-r--r--   1 gap    13626 Mar 28 16:31 README
    drwxr-xr-x   2 gap      512 Apr 10 13:30 bin
    drwxr-xr-x   2 gap      512 Apr  9 20:28 examples
    drwxr-xr-x   2 gap      512 Apr 10 14:22 gap
    -rw-r--r--   1 gap     5272 Apr 10 13:34 init.g
    drwxr-xr-x   2 gap     1024 Apr 10 13:41 src
    -rwxr-xr-x   1 gap      525 Mar 28 15:50 testSq |

Typing 'make' will produce a list of possible target.

|    gap@tiffy:../anusq > make
    usage: 'make <target> EXT=<ext>'  where <target> is one of
    'bsd-gcc'    for Berkeley UNIX with GNU cc 2
    'bsd-cc'     for Berkeley UNIX with cc
    'usg-gcc'    for System V UNIX with cc
    'usg-cc'     for System V UNIX with cc
    'clean'      remove all created files

       where <ext> should be a sensible extension, i.e.,
       'EXT=-sun-sparc-sunos' for SUN 4 or 'EXT=' if the SQ only
       runs on a single architecture

       additional C compiler and linker flags can be passed with
       'make <target> COPTS=<compiler-opts> LOPTS=<linker-opts>',
       i.e., 'make bsd-cc COPTS="-DTAILS -DCOLLECT"', see the
       README file for details on TAILS and COLLECT.

       set ME if the vector enumerator is not started with the
       command '`pwd`/../ve/bin/me',
       i.e., 'make bsd-cc ME=/home/ve/bin/me'.|

Select  the target you  need.  The DECstations  are running Ultrix, so we
chose 'bsd-gcc'.

|    gap@tiffy:../anusq > make bsd-gcc EXT=-dec-mips-ultrix
    # you will see a lot of messages |

Now repeat the compilation for the Sun run SunOS  5.3. *Do not* forget to
clean up.

|    gap@tiffy:../anusq > rlogin galois
    gap@galois:~ > cd gap3r4p0/pkg/anusq
    gap@galois:../anusq > make clean
    gap@galois:../src > make usg-cc EXT=-sun-sparc-sunos
    # you will see a lot of messages and a few warnings
    gap@galois:../anusq > exit
    gap@tiffy:../anusq > |

Switch into the subdirectory 'bin/'  and create a  script which will call
the correct binary for each machine. A skeleton  shell script is provided
in 'bin/Sq.sh'.

|    gap@tiffy:../anusq > cd bin
    gap@tiffy:../bin > cat > sq
    |\#|!/bin/csh
    switch ( `hostname` )
      case 'tiffy':
        exec $0-dec-mips-ultrix $* ;
        breaksw ;
      case 'bert':
        setenv ANUSQ_ME_EXEC /rem/tiffy/usr/local/bin/me ;
        exec $0-dec-mips-ultrix $* ;
        breaksw ;
      case 'galois':
        exec $0-sun-sparc-sunos $* ;
        breaksw ;
      default:
        echo "sq: sorry, no executable exists for this machine" ;
        breaksw ;
    endsw
    |<ctr>-'D'|
    gap@tiffy:../bin > chmod 755 Sq
    gap@tiffy:../bin > cd .. |

Now it is time to test  the installation.  The  first test will only test
the ANU Sq.

|    gap@tiffy:../anusq > ./testSq
    Testing examples/grp1.fp  . . . . . . . . succeeded
    Testing examples/grp2.fp  . . . . . . . . succeeded
    Testing examples/grp3.fp  . . . . . . . . succeeded |

If there is a problem  and you get an error message saying 'me not found',
set the  environment variable 'ANUSQ\_ME\_EXEC'  to the module enumerator
executable and try again.

The  second test will  test the link between {\GAP}   and the ANU Sq.  If
everything goes well you should not see any message.

|    gap@tiffy:../anusq > gap -b
    gap> RequirePackage( "anusq" );
    gap> ReadTest( "gap/test1.tst" );
    gap> |

You may now repeat the tests for the other machines.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{GRAPE Package}

{\GRAPE}  (Version~2.2)  is  a system for  computing with graphs,  and is
primarily  designed  for constructing  and analysing  graphs  related  to
groups and finite geometries.

The vast  majority  of {\GRAPE}  functions  are written entirely  in  the
{\GAP}  language,  except  for  the  automorphism  group  and isomorphism
testing  functions,  which use  Brendan  McKay\'s  {\nauty} (Version~1.7)
package \cite{Nau90}.

Except for the {\nauty}~1.7 package included with  {\GRAPE}, the {\GRAPE}
system  was designed  and  written by Leonard   H.   Soicher,  School  of
Mathematical Sciences, Queen Mary  and Westfield College,  Mile End Road,
London E1~4NS, U.K., email\: L.H.Soicher@qmw.ac.uk.

Please tell Leonard  Soicher if  you install  {\GRAPE}.  Also, if you use
{\GRAPE} to solve a problem then also tell him about it, and reference

L.H.Soicher, {\GRAPE\:} a system for computing with graphs and groups, in
<Groups and Computation>  (L. Finkelstein and W.M. Kantor, eds.),  DIMACS 
Series  in Discrete  Mathematics and  Theoretical Computer Science  *11*, 
pp. 287--291.

If you use the automorphism group and graph isomorphism testing functions
of {\GRAPE} then you  are  also using Brendan McKay\'s  {\nauty} package,
and should also reference

B.D.McKay,   {\nauty}  users  guide  (version   1.5),  Technical   Report
TR-CS-90-02, Computer Science Department, Australian National University,
1990.

This document is in 'nauty17/nug.alw' in  postscript form.  There is also
a readme for {\nauty} in 'nauty17/read.me'.

*Warning*  A canonical  labelling  given  by  {\nauty} can  depend on the
version of  {\nauty}  (Version~1.7 in  {\GRAPE}~2.2),  certain parameters
of {\nauty} (always set  the  same  by {\GRAPE}~2.2) and the compiler and 
computer used.  If  you  use  a  canonical labelling  (say by  using  the 
'IsIsomorphicGraph' function) of  a graph stored on a file, then you must  
be sure that this field  was created in the same environment in which you 
are  presently  computing.  If in doubt, unbind the  'canonicalLabelling' 
field of the graph.

The only incompatible changes from  {\GRAPE}~2.1 to {\GRAPE}~2.2 are that
'Components' is now called 'ConnectedComponents',  and 'Component' is now
called 'ConnectedComponent', and only works for simple graphs.

{\GRAPE} is provided \"as is\", with no warranty whatsoever.  Please read 
the  copyright  notice  in the file 'COPYING'.

Please   send   comments    on   {\GRAPE},   bug    reports,   etc.    to
L.H.Soicher@qmw.ac.uk.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installing the GRAPE Package}

{\GRAPE} consists  of  two  parts.  The first  part  is  a set of  {\GAP}
functions  for constructing and analysing  graphs,  which will run on any
machine that supports  {\GAP}.  The second part is  based on the {\nauty}
package written  in C  and  computes automorphism  groups of  graphs, and
tests  for graph isomorphisms.  This  part  of the  package  can only  be
installed under UNIX.

If you  got a complete binary and  source distribution for  your machine,
nothing   has to be   done  if you  want   to use {\GRAPE}  for  a single
architecture.  If you  want to  use  {\GRAPE} for machines with different
architectures  skip the extraction and   compilation part of this section
and proceed with the creation of shell scripts described below.

If you  got a complete source distribution,  skip the  extraction part of
this section and proceed with the compilation part below.

In the example we will assume that you, as user 'gap', are installing the
{\GRAPE}  package  for  use  by  several  users  on  a  network   of  two
DECstations, called  'bert' and 'tiffy',  and a PC running 386BSD, called
'waldorf'.  We assume that {\GAP}  is  also  installed on  these machines
following the instructions given in "Installation of GAP for UNIX".

Note that certain parts  of  the  output  in the examples should  only be
taken as rough outline, especially file sizes and file dates are *not* to
be taken literally.

First of  all you have to get  the file  'grape.zoo' (see "Getting GAP").
Then you must locate the {\GAP} directories containing 'lib/' and 'doc/',
this is usually  'gap3r4p0' where '0' is to   be replaced by  current the
patch level.

|    gap@tiffy:~ > ls -l
    drwxr-xr-x  11 gap      gap          1024 Nov  8  1991 gap3r4p0
    -rw-r--r--   1 gap      gap        342865 May 27 15:16 grape.zoo
    gap@tiffy:~ > ls -l gap3r4p0
    drwxr-xr-x   2 gap      gap          3072 Nov 26 11:53 doc
    drwxr-xr-x   2 gap      gap          1024 Nov  8  1991 grp
    drwxr-xr-x   2 gap      gap          2048 Nov 26 09:42 lib
    drwxr-xr-x   2 gap      gap          2048 Nov 26 09:42 src
    drwxr-xr-x   2 gap      gap          1024 Nov 26 09:42 tst|

Unpack the  package using 'unzoo'  (see "Installation  of GAP for UNIX").
Note that you must  be in the directory  containing 'gap3r4p0'  to unpack
the files.   After   you have unpacked  the  source  you may   remove the
*archive-file*.

|    gap@tiffy:~ > unzoo x grape.zoo
    gap@tiffy:~ > ls -l gap3r4p0/pkg/grape
    -rw-r--r--    1 gap   1063 May 22 14:40 COPYING
    -rw-r--r--    1 gap   2636 May 28 09:58 Makefile
    -rw-r--r--    1 gap   4100 May 24 14:57 README
    drwxr-xr-x    2 gap    512 May 28 11:36 bin
    drwxr-xr-x    2 gap    512 May 25 14:52 doc
    drwxr-xr-x    2 gap    512 May 22 16:59 grh
    -rw-r--r--    1 gap  82053 May 27 12:19 init.g
    drwxr-xr-x    2 gap    512 May 27 14:18 lib
    drwxr-xr-x    2 gap    512 May 28 11:36 nauty17
    drwxr-xr-x    2 gap    512 May 22 12:32 prs
    drwxr-xr-x    2 gap    512 May 28 11:36 src |

You are now able  to use the  all functions described in  chapter "Grape"
except 'AutGroupGraph' and  'IsIsomorphicGraph'  which use the   {\nauty}
package.

|    gap> RequirePackage("grape");

    Loading  GRAPE 2.2  (GRaph Algorithms using PErmutation groups),
    by L.H.Soicher@qmw.ac.uk.

    gap> gamma := JohnsonGraph( 4, 2 );
    rec(
      isGraph := true,
      order := 6,
      group := Group( (1,5)(2,6), (1,3)(4,6), (2,3)(4,5) ),
      schreierVector := [ -1, 3, 2, 3, 1, 2 ],
      adjacencies := [ [ 2, 3, 4, 5 ] ],
      representatives := [ 1 ],
      names := [ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ], [ 2, 3 ], [ 2, 4 ],
          [ 3, 4 ] ],
      isSimple := true ) |

If the   documentation is not already   installed or an older  version is
installed, copy the  file  'doc/grape.tex' into the 'doc/'  directory and
run  latex again (see "Installation of   GAP for UNIX").   In general the
documentation   will already be   installed  so you    can just skip  the
following  step.  

|    gap@tiffy:~ > cd gap3r4p0/pkg/grape
    gap@tiffy:../grape > cp doc/grape.tex ../../doc
    gap@tiffy:../grape > cd ../../doc
    gap@tiffy:../doc > latex manual
    # a few messages about undefined references
    gap@tiffy:../doc > latex manual
    # a few messages about undefined references
    gap@tiffy:../doc > makeindex manual
    # 'makeindex' prints some diagnostic output
    gap@tiffy:../doc > latex manual
    # there should be no warnings this time
    gap@tiffy:../doc cd ../pkg/grape |

In order to compile {\nauty} and the filters used by {\GRAPE} to interact
with {\nauty} type 'make' to get a list of support machines.

|    gap@tiffy:../grape > make
    usage: 'make <target>' EXT=<ext> where target is one of
    'dec-mips-ultrix-cc'   for DECstations running Ultrix with cc
    'hp-hppa1.1-hpux-cc'   for HP 9000/700 under HP-UX with cc
    'hp-hppa1.0-hpux-cc'   for HP 9000/800 under HP-UX with cc
    'ibm-i386-386bsd-gcc2' for IBM PCs under 386BSD with GNU cc 2
    'ibm-i386-386bsd-cc'   for IBM PCs under 386BSD with cc (GNU)
    'sun-sparc-sunos-cc'   for SUN 4 under SunOS with cc
    'bsd'                  for others under Berkeley UNIX with cc
    'usg'                  for others under System V UNIX with cc

    where <ext> should be a sensible extension, i.e.,
    'EXT=.sun' for SUN or 'EXT=' if GRAPE only runs
    on a single architecture |

Select the target you need.  In your case we first compile the DECstation
version.   We use  the  extension '-dec-mips-ultrix',  which creates  the
binaries \\
'dreadnaut-dec-mips-ultrix', 'drcanon3-dec-mips-ultrix', \\
'gap3todr-dec-mips-ultrix' and 'drtogap3-dec-mips-ultrix' \\
in the 'bin/' directory.

|    gap@tiffy:../grape > make dec-mips-ultric-cc EXT=-dec-mips-ultrix
    # you will see a lot of messages |

Now repeat the compilation for the PC. *Do not* forget to clean up.

|    gap@tiffy:../grape > rlogin waldorf
    gap@waldorf:~ > cd gap3r4p0/pkg/grape
    gap@waldorf:../grape > make clean
    gap@waldorf:../grape > make ibm-i386-386bsd-gcc2 EXT=-ibm-i386-386bsd
    # you will see a lot of messages
    gap@waldorf:../grape > exit
    gap@tiffy:../grape > |

Switch into  the subdirectory 'bin/'  and create four shell scripts which
will call the correct binary for each machine. Skeleton shell scripts are
provided in 'bin/dreadnaut.sh', 'bin/drcanon3.sh', etc.

|    gap@tiffy:../grape > cat > bin/dreadnaut
    |\#|!/bin/csh
    switch ( `hostname` )
      case 'tiffy':
      case 'bert':
        exec $0-dec-mips-ultrix $* ;
        breaksw ;
      case 'waldorf':
        exec $0-ibm-i386-386bsd $* ;
        breaksw ;
      default:
        echo "dreadnaut: sorry, no executable exists for this machine" ;
        breaksw ;
    endsw
    |<ctr>-'D'|
    gap@tiffy:../grape > chmod 755 bin/dreadnaut|

You  must also create similar  shell scripts for  'drcanon3', 'drtogap3',
and 'gap3todr'.  Note  that if you  are using  {\GRAPE} only on a  single
architecture you  can  specify  an empty  extension  using  'EXT='  as  a
parameter  to 'make'.   In  this  case  *do not*  create the  above shell
scripts.  The  following example will test the interface between {\GRAPE}
and {\nauty}.

|    gap> IsIsomorphicGraph( JohnsonGraph(7,3), JohnsonGraph(7,4) );
    true
    gap> AutGroupGraph( JohnsonGraph(4,2) );
    Group( (3,4), (2,3)(4,5), (1,2)(5,6) ) |

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{MeatAxe Package}

The {\MeatAxe} package provides algorithms for computing with finite field
matrices, permutations, matrix groups, matrix algebras, and their modules.

Every such object exists outside {\GAP} on a file, and {\GAP} is only
responsible for handling these files using the appropriate programs.

Details about the standalone can be found in~\cite{Rin93}.
This implementation was developed in C by

Michael Ringe\\
Lehrstuhl D f{\accent127 u}r Mathematik\\
RWTH Aachen\\
52062 Aachen, Germany

e-mail mringe@math.rwth-aachen.de

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installing the MeatAxe Package}

The {\MeatAxe} is written in C, and it is assumed that the package is
installed  under UNIX.  Some other systems --currently MS-DOS and VM/CMS--
are supported, but this applies only for the standalone and not for the
use of the {\MeatAxe} from within {\GAP} (see the {\MeatAxe}
manual~\cite{Rin93} for details of the installation in these cases).

If you got  a complete binary and  source distribution, skip the extraction
and compilation part of this section.  All what you have to do in this case
is to make the executables accessible via a pathname that contains the
hostname of the machine; this is best done by creating suitable links, as
is described at the end of this section.

If you  got a complete source distribution,  skip the  extraction part of
this section and proceed with the compilation part below.

In the example we will assume that you, as user 'gap', are installing the
{\MeatAxe} package for use by several users on a network of two DECstations,
called 'bert' and 'tiffy', and a NeXTstation, called 'bjerun'. We  assume
that  {\GAP}  is  also   installed  on  these   machines  following   the
instructions given in "Installation of GAP for UNIX".

Note that certain parts  of  the  output  in the examples should  only be
taken as rough outline, especially file sizes and file dates are *not* to
be taken literally.

First of all you have to get the file 'meataxe.zoo' (see "Getting GAP").
Then you must locate the {\GAP} directory containing 'lib/' and 'doc/',
this is usually 'gap3r4p0' where '0' is to be be replaced by the patch
level.

|    gap@tiffy:~ > ls -l
    drwxr-xr-x  11 gap      gap          1024 Nov  8  1991 gap3r4p0
    -rw-r--r--   1 gap      gap        359381 May 11 11:34 meataxe.zoo
    gap@tiffy:~ > ls -l gap3r4p0
    drwxr-xr-x    2 gap          3072 Nov 26 11:53 doc
    drwxr-xr-x    2 gap          1024 Nov  8  1991 grp
    drwxr-xr-x    2 gap          2048 Nov 26 09:42 lib
    drwxr-xr-x    2 gap          2048 Nov 26 09:42 src
    drwxr-xr-x    2 gap          1024 Nov 26 09:42 tst|

Unpack the package using 'unzoo'  (see  "Installation of GAP for  UNIX").
Note  that you must  be in the  directory containing 'gap3r4p0' to unpack
the files.  After   you have  unpacked the source   you   may remove  the
*archive-file*.

|    gap@tiffy:~ > unzoo x meataxe.zoo
    gap@tiffy:~ > ls -l gap3r4p0/pkg/meataxe
    -rw-r--r--    1 gap         17982 Aug  6  1993 COPYING
    -rw-r--r--    1 gap          3086 Mar 15 15:07 README
    drwxr-xr-x    3 gap           512 Mar 26 18:01 bin
    drwxr-xr-x    2 gap           512 Feb 25 12:07 doc
    drwxr-xr-x    2 gap           512 May 11 09:34 gap
    -rw-r--r--    1 gap          1023 May 11 09:34 init.g
    drwxr-xr-x    2 gap          1024 Mar 26 18:02 lib
    drwxr-xr-x    2 gap          1536 Mar 26 18:02 src
    drwxr-xr-x    2 gap           512 Mar 15 11:36 tests |

Switch into the directory 'bin/', edit the 'Makefile', and follow the
instructions given there.  In most cases it will suffice to choose the
right 'COMPFLAGS'.  Then type  'make' to compile  the {\MeatAxe}.
In  your case we first compile  the  DECstation version.

|    gap@tiffy:~ > cd gap3r4p0/pkg/meataxe/bin
    gap@tiffy:../bin > make
    |\#| you will see a lot of messages |

The executables reside in a directory with the same name as the host, in
this case this is 'tiffy'.  The programs will be called from {\GAP} using
the hostname, thus for every machine that shall run the {\MeatAxe} under
{\GAP} such a directory is necessary.  In your case there is a second
DEC-station called 'bert' which can use the same executables, we make them
available via a link.

|    gap@tiffy:../bin > ln -s tiffy bert |

Now repeat the compilation  for the NeXTstation.  If you want to save space
you can clean up using 'make clean' but this is not necessary.
If the 'make' run was interrupted you can return to the prior situation
using 'make delete', and then call 'make' again.

|    gap@tiffy:../bin > rlogin bjerun
    gap@bjerun:~ > cd gap3r4p0/pkg/meataxe/bin
    gap@bjerun:../bin > make clean
    gap@bjerun:../bin > make
    |\#| you will see a lot of messages
    gap@bjerun:../bin > exit
    gap@tiffy:../bin > |

Now it is time to test the package.  Switch into the directory '../tests/'
and type './testmtx'.  You should get no error messages, and end up with
the message 'all tests passed'.

|    gap@tiffy:../bin > cd ../tests
    gap@tiffy:../tests > ./testmtx
    |\#| you will see a lot of messages
    gap@tiffy:../tests > |

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{NQ Package}
\index{NilpotentQuotient}

'NilpotentQuotient( <F> )' \\
'NilpotentQuotient( <F>, <c> )'

'NilpotentQuotient'   computes the  quotient    groups of the finitely
presented group <F> successively modulo the terms of the lower central
series  of  <F>. If it  terminates, it returns a list  $L$. The $i$-th
entry of $L$ contains the non-trivial abelian invariants of the $i$-th
factor   of the lower   central series  of   <F> (the  largest abelian
quotient being the first factor).

'NilpotentQuotient'  accepts  a positive  integer <c>   as an optional
second argument.    If the second  argument is  present,  the function
computes the quotient group of <F> modulo the <c>-th term of the lower
central series of <F> (the commutator subgroup is the first term).

|    gap> RequirePackage("nq");
    gap> a := AbstractGenerator( "a" );;
    gap> b := AbstractGenerator( "b" );;
    gap>
    gap> G := rec( generators := [a, b],
    >     relators   := [ LeftNormedComm( b,a,a,a,a ),
    >                     LeftNormedComm( b,a,b,b,b ),
    >                     LeftNormedComm( b,a,a*b,a*b,a*b ),
    >                     LeftNormedComm( b,a,a*b^2,a*b^2,a*b^2 ),
    >                     LeftNormedComm( b,a,b,a,a,a ),
    >                     LeftNormedComm( b,a,a,b,b,b ) ]
    >    );;
    gap>
    gap> NilpotentQuotient( G, 6 );
    [ [ 0, 0 ], [ 0 ], [ 0, 0 ], [ 0, 0, 0 ], [ 2, 0, 0 ], [ 2, 10, 0 ] ]|

This implementation was developed in C by

Werner Nickel\\
School of Mathematical Sciences\\
Australian National University\\
Canberra, ACT 0200

e-mail werner@pell.anu.edu.au

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installing the NQ Package}

The NQ is written in C and the package can only be installed  under UNIX.
It  has been tested  on DECstation  running Ultrix, a NeXTstation running
NeXT-Step  3.0, and  SUNs  running SunOS.  It  requires  the GNU multiple
precision  arithmetic.  Make  sure that  this library is installed before
trying to install the NQ.

If you got  a complete binary and  source distribution for your  machine,
nothing  has   to be done  if   you want to  use    the NQ for   a single
architecture.  If  you  want to use  the NQ  for  machines with different
architectures skip  the extraction and  compilation part of  this section
and proceed with the creation of shell scripts described below.

If you  got a complete source distribution,  skip the  extraction part of
this section and proceed with the compilation part below.

In the example we will assume that you, as user 'gap', are installing the
NQ  package for  use by  several users on  a network of two  DECstations,
called 'bert' and 'tiffy', and a NeXTstation, called 'bjerun'. We  assume
that  {\GAP}  is  also   installed  on  these   machines  following   the
instructions given in "Installation of GAP for UNIX".

Note that certain parts  of  the  output  in the examples should  only be
taken as rough outline, especially file sizes and file dates are *not* to
be taken literally.

First of all you have to get the file 'nq.zoo' (see "Getting GAP").  Then
you must locate the {\GAP} directories containing 'lib/' and 'doc/', this
is usually 'gap3r4p0' where '0' is to be be replaced by the patch level.

|    gap@tiffy:~ > ls -l
    drwxr-xr-x  11 gap      gap          1024 Nov  8  1991 gap3r4p0
    -rw-r--r--   1 gap      gap        106307 Jan 24 15:16 nq.zoo
    gap@tiffy:~ > ls -l
    drwxr-xr-x   2 gap      gap          3072 Nov 26 11:53 doc
    drwxr-xr-x   2 gap      gap          1024 Nov  8  1991 grp
    drwxr-xr-x   2 gap      gap          2048 Nov 26 09:42 lib
    drwxr-xr-x   2 gap      gap          2048 Nov 26 09:42 src
    drwxr-xr-x   2 gap      gap          1024 Nov 26 09:42 tst|

Unpack the package using 'unzoo'  (see  "Installation of GAP for  UNIX").
Note  that you must  be in the  directory containing 'gap3r4p0' to unpack
the files.  After   you have  unpacked the source   you   may remove  the
*archive-file*.

|    gap@tiffy:~ > unzoo x nq.zoo
    gap@tiffy:~ > ls -l gap3r4p0/pkg/nq
    drwxr-xr-x   2 gap    gap      1024 Jan 24 21:00 bin
    drwxr-xr-x   2 gap    gap      1024 Jan 19 11:33 examples
    drwxr-xr-x   2 gap    gap      1024 Jan 24 21:03 gap
    lrwxrwxrwx   1 gap    gap         8 Jan 19 11:33 init.g
    drwxr-xr-x   2 gap    gap      1024 Jan 24 21:04 src
    -rwxr--r--   1 gap    gap       144 Dec 28 15:08 testNq |

Switch into the directory 'src/' and type  'make' to compile  the NQ.  If
the header files for  the GNU multiple  precision arithmetic are *not* in
'/usr/local/include' you must set 'GNUINC' to  the correct directory.  If
the    library  for the   GNU  multiple  precision   arithmetic  is *not*
'/usr/local/lib/libmp.a'  you must set 'GNULIB'.   In  your case we first
compile  the  DECstation version. If  your  operating  system  *does not*
provide a function 'getrusage' start make with 'COPTS=-DNO\_GETRUSAGE'.

|    gap@tiffy:~ > cd gap3r4p0/pkg/nq/src
    gap@tiffy:../src > make GNUINC=/usr/gnu/include \
                            GNULIB=/usr/gnu/lib/libmp.a
    |\#| you will see a lot of messages |

Now it is possible to test the standalone.

|    gap@tiffy:../src > cd ..
    gap@tiffy:../nq > testNq |

If  'testNq' reports a  difference others then  machine name,  runtime or
size, check the GNU multiple precision  arithmetic and warnings generated
by  'make'.   If  'testNq'  succeeded  ,   move  the  executable  to  the
'bin/' directory.

|    gap@tiffy:../nq > mv src/nq bin/nq-dec-mips-ultrix |

Now repeat the compilation  for the NeXTstation. *Do not* forget to clean
up.

|    gap@tiffy:../nq > rlogin bjerun
    gap@bjerun:~ > cd gap3r4p0/pkg/nq/src
    gap@bjerun:../src > make clean
    gap@bjerun:../src > make
    |\#| you will see a lot of messages
    gap@bjerun:../src > mv nq ../bin/nq-next-m68k-mach
    gap@bjerun:../src > exit
    gap@tiffy:../src > |

Switch into the  subdirectory 'bin/' and  create a script which will call
the correct binary for each machine.  A skeleton shell script is provided
in 'bin/nq.sh'.

|    gap@tiffy:../src > cd ..
    gap@tiffy:../nq > cat > bin/nq
    |\#|!/bin/csh
    switch ( `hostname` )
      case 'bert':
      case 'tiffy':
        exec $0-dec-mips-ultrix $* ;
        breaksw ;
      case 'bjerun':
        exec $0-next-m68k-mach $* ;
        breaksw ;
      default:
        echo "nq: sorry, no executable exists for this machine" ;
        breaksw ;
    endsw
    |<ctr>-'D'|
    gap@tiffy:../nq > chmod 755 bin/nq|

Now it is time  to test the  package.  Assuming that  'testNq' worked the
following will test the link to {\GAP}.

|    gap@tiffy:../nq > gap -b
    gap> RequirePackage( "nq" );
    gap> ReadTest( "gap/nq.tst" );
    gap> |

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{SISYPHOS Package}

{\SISYPHOS} provides  access  to  implementations   of  algorithms for
dealing with $p$-groups and their modular group algebras.  At the moment
only the programs for $p$-groups are accessible via {\GAP}.
They can be used to compute isomorphisms between $p$-groups, and
automorphism groups of $p$-groups.

The description of the functions available in the  {\SISYPHOS} package is
given in chapter "Sisyphos".

% A reader interested  in details  of the  algorithms  and explanations  of
% terms  used  is  referred  to  \cite{...}

For  details about  the implementation and the standalone version see the
README. This implementation was developed in C by

Martin Wursthorn\\
Math. Inst. B, 3. Lehrstuhl\\
Universit{\accent127 a}t Stuttgart

e-mail pluto@machnix.mathematik.uni-stuttgart.de\\
Tel.: +49 (0)711 685 5517\\
Fax.: +49 (0)711 685 5322

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installing the SISYPHOS Package}

{\SISYPHOS} is written in ANSI-C and should run on every UNIX system
(and some non-UNIX systems) that provides an ANSI-C Compiler, e.g., the
GNU C compiler.  {\SISYPHOS} has been ported to IBM RS6000 running
AIX 3.2, HP9000 7xx running HP-UX 8.0/9.0, PC 386/486 running Linux,
PC 386/486 running DOS or OS/2 with emx
and ATARI ST/TT running TOS.

In the example we will assume that you, as user 'gap', are installing the
{\SISYPHOS}  package  for  use  by several  users  on  a  network  of two
DECstations, called  'bert' and 'tiffy', and  a 486 PC, called 'waldorf'.
We assume that {\GAP}  is also installed  on these machines following the
instructions given in "Installation of GAP for UNIX".

Note that certain parts  of  the  output  in the examples should  only be
taken as rough outline, especially file sizes and file dates are *not* to
be taken literally.

First of all you have to get the file 'sisyphos.zoo' (see "Getting GAP").
Then you must locate the {\GAP} directories containing 'lib/' and 'doc/',
this is usually 'gap3r4p0' where '0' is to be be replaced by the patch
level.

|    gap@tiffy:~ > ls -l
    drwxr-xr-x  11 gap     1024 Nov  8  1991 gap3r4p0
    -rw-r--r--   1 gap   245957 Dec 27 15:16 sisyphos.zoo
    gap@tiffy:~ > ls -l gap3r4p0
    drwxr-xr-x   2 gap     3072 Nov 26 11:53 doc
    drwxr-xr-x   2 gap     1024 Nov  8  1991 grp
    drwxr-xr-x   2 gap     2048 Nov 26 09:42 lib
    drwxr-xr-x   2 gap     2048 Nov 26 09:42 src
    drwxr-xr-x   2 gap     1024 Nov 26 09:42 tst |

Unpack the package using 'unzoo'  (see "Installation  of GAP for  UNIX").
Note that you must be  in the directory  containing 'gap3r4p0' to  unpack
the  files.  After you    have unpacked the  source   you may  remove the
*archive-file*.

|    gap@tiffy:~ > unzoo x sisyphos.zoo
    gap@tiffy:~ > ls -l gap3r4p0/pkg/sisyphos
    -rw-r--r--  1 gap          9496 Feb 11  1993 README
    drwxr-xr-x  3 gap           512 Oct 19 10:24 doc
    drwxr-xr-x  2 gap           512 Oct 15 14:30 groups
    drwxr-xr-x  2 gap           512 Apr  1  1993 ideal
    -rw-r--r--  1 gap         22072 Oct 19 10:23 init.g
    drwxr-xr-x  2 gap          1536 Oct 15 14:49 src |

Switch into the directory 'src/'.  It contains the makefile for {\SISYPHOS}.

|gap@tiffy:../src > make
usage: 'make <target>'  where target is one of
'hp700-hpux-gcc2'    for HP 9000/7xx under HP-UX with GNU cc 2
'hp700-hpux-cc'      for HP 9000/7xx under HP-UX with cc
'hp700-hpux-cci'     for HP 9000/7xx under HP-UX with cc -
                       generate version for profile dependent optimization
'hp700-hpux-ccp'     for HP 9000/7xx under HP-UX with cc -
                       relink with profile dependent optimization
'ibm6000-aix-cc'     for IBM RS/6000 under AIX with cc
'ibmpc-linux-gcc2'   for IBM PCs under Linux with GNU cc 2
'ibmpc-emx-gcc2'     for IBM PCs under DOS or OS/2 2.0 with emx
'generic-unix-gcc2'  for other UNIX machines with GNU cc 2
                     this should work on most machines |

Select the  target  you need.   In our case we  first
compile the  DECstation version.  We assume  that the  command  to  start
{\GAP}   is   '/usr/local/bin/gap'   for   'tiffy'   and   'waldorf'   and
'/rem/tiffy/usr/local/bin/gap' for 'bert'.

|    gap@tiffy:../src > make generic-unix-gcc2
    # you will see a lot of messages and maybe a few warnings |

You should test the standalone now.  The following command should run
without any comment.  This will work, however, only for UNIX machines.

|    gap@tiffy:../src > testsis |

The executables will be collected in the '/bin' directory, so we move that
for the DECstation there.

|    gap@tiffy:../src > mv sis ../bin/sis.ds |

Now repeat the compilation  for the PC. *Do not* forget to clean up.

|    gap@tiffy:../src > rlogin waldorf
    gap@waldorf:~ > cd gap3r4p0/pkg/sisyphos/src
    gap@waldorf:../src > make clean
    gap@waldorf:../src > make generic-unix-gcc2
    # you will see a lot of messages and maybe a few warnings |

Test the executable (under UNIX only), and move it to the right place.

|    gap@waldorf:../src > testsis
    gap@waldorf:../src > mv sis ../bin/sis.386bsd
    gap@waldorf:../src > exit
    gap@tiffy:../src > |

Switch into the subdirectory  'bin/' and create a script  which will call
the correct binary for each machine.

|    gap@tiffy:../src > cd ..
    gap@tiffy:../sisyphos > cat > bin/sis
    |\#|!/bin/csh
    switch ( `hostname` )
      case 'bert':
      case 'tiffy':
        exec ~gap/3.2/pkg/sisyphos/bin/sis.ds $* ;
        breaksw ;
      case 'waldorf':
        exec ~gap/3.2/pkg/sisyphos/bin/sis.386bsd $* ;
        breaksw ;
      default:
        echo "sis: sorry, no executable exists for this machine" ;
        breaksw ;
    endsw
    |<ctr>-'D'|
    gap@tiffy:../sisyphos > chmod 755 bin/sis|

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Smash Package}

This share library provides functions which may be  used to construct and
investigate  the    structure  of matrix   groups    defined over  finite
fields. These functions  permit the  user to  construct certain  types of
matrix groups and G-modules; to test whether a G-module is irreducible or
absolutely irreducible;   to    decide whether   a  group  has    certain
decomposition with  respect  to a normal  subgroup; and  to select random
elements with certain properties.

The  code was developed as part  of the on-going project to \"recognise\"
the Aschbacher categories of matrix groups defined over finite fields.

The interested reader is   referred to \cite{HR94},  \cite{HLOR94a},  and
\cite{HLOR94b} for details of the algorithms used.

Smash was developed by

Derek Holt, Mathematics Institute, Warwick \\
dfh@maths.warwick.ac.uk

Charles Leedham-Green, School of Mathematical Studies, QMW \\
C.R.Leedham-Green@qmw.ac.uk

Eamonn O\'Brien, School of Mathematical Sciences, ANU \\
Eamonn.OBrien@maths.anu.edu.au

Sarah Rees, Department of Mathematics and Statistics, Newcastle \\
Sarah.Rees@newcastle.ac.uk

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installing the Smash Package}

The smash package  is completely written  in the {\GAP} language, it does
not require any additional programs and/or compilations.   It will run on
any computer   that runs {\GAP}.  To  access  smash, use 'RequirePackage'
(see "RequirePackage").

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Vector Enumeration Package}

The {\VE} package provides access to the implementation of the ``linear
Todd-Coxeter\'\' method for computing matrix representations of finitely
presented algebras.

The description of the functions available in the {\VE} package is
given in chapter "Vector Enumeration".

For  details about  the implementation and the standalone version see the
README. This implementation was developed in C by

Stephen A. Linton \\
Division of Computer Science \\
School of Mathematical and Computational Science \\
University of St. Andrews \\
North Haugh \\
St. Andrews \\
Fife \\
KY10 2SA \\
SCOTLAND

e-mail sal@cs.at-andrews.ac.uk \\
Tel.:+44 334 63239 \\
Fax.: +44 334 63278

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installing the Vector Enumeration Package}

The Vector Enumerator (VE) is written in C and the package can only be
installed under UNIX.  It has been tested on DECstation running
Ultrix, a 486 running NetBSD, and SUNs running SunOS.

The parts of the package that deal with rationals require the GNU multiple
precision arithmetic library GMP.  Make sure that this library is installed
before trying to install VE.

If you got  a complete binary and  source distribution for your  machine,
nothing  has   to be done  if   you want to  use    the VE for   a single
architecture.  If  you  want to use  the VE  for  machines with different
architectures skip  the extraction and  compilation part of  this section
and proceed with the creation of shell scripts described below.

If you  got a complete source distribution,  skip the  extraction part of
this section and proceed with the compilation part below.

In the example we will assume that you, as user 'gap', are installing the
VE  package for  use by  several users on  a network of two  DECstations,
called 'bert' and 'tiffy', and a NeXTstation, called 'bjerun'. We  assume
that  {\GAP}  is  also   installed  on  these   machines  following   the
instructions given in "Installation of GAP for UNIX".

Note that certain parts  of  the  output  in the examples should  only be
taken as rough outline, especially file sizes and file dates are *not* to
be taken literally.

First of all you have to get the file 've.zoo' (see "Getting GAP").  Then
you must locate the {\GAP} directories containing 'lib/' and 'doc/', this
is usually 'gap3r4p0' where '0' is to be be replaced by the patch level.

|    gap@tiffy:~ > ls -l
    drwxr-xr-x  11 gap      gap          1024 Nov  8  1991 gap3r4p0
    -rw-r--r--   1 gap      gap        106307 Jan 24 15:16 ve.zoo
    gap@tiffy:~ > ls -l gap3r4p0
    drwxr-xr-x   2 gap      gap          3072 Nov 26 11:53 doc
    drwxr-xr-x   2 gap      gap          1024 Nov  8  1991 grp
    drwxr-xr-x   2 gap      gap          2048 Nov 26 09:42 lib
    drwxr-xr-x   2 gap      gap          2048 Nov 26 09:42 src
    drwxr-xr-x   2 gap      gap          1024 Nov 26 09:42 tst|

Unpack the package using 'unzoo'  (see  "Installation of GAP for  UNIX").
Note  that you must  be in the  directory containing 'gap3r4p0' to unpack
the files.  After   you have  unpacked the source   you   may remove  the
*archive-file*.

|    gap@tiffy:~ > unzoo x ve.zoo
     gap@tiffy:~ > ls -l gap3r4p0/pkg/ve
     -rw-r--r--  1 sam         16761 May 10 17:39 Makefile
     -rw-r-----  1 sam          1983 May  6  1993 README
     drwxr-xr-x  2 sam           512 May 10 17:41 bin
     drwxr-xr-x  2 sam           512 May 10 17:34 docs
     drwxr-xr-x  2 sam           512 May 10 17:34 examples
     drwxr-xr-x  3 sam           512 Mar 28 17:55 gap
     -rw-r--r--  1 sam           553 Mar 24 18:18 init.g
     drwxr-xr-x  5 sam          1024 May 10 17:36 src |

Switch into the directory 've/' and type 'make' to see a list of targets
for compilation; then type 'make <target>' to compile VE, where <target>
is the target that is closest to your machine.  If the header files for
the GNU multiple precision arithmetic are *not* in '/usr/local/include'
you must set 'INCDIRGMP' to the correct directory.  If the library for
the GNU multiple precision arithmetic is *not* '/usr/local/lib/libgmp.a'
you must set 'LIBDIRGMP'.  In this case we first compile the
DECstation version.

|    gap@tiffy:~ > cd gap3r4p0/pkg/ve
    gap@tiffy:../ve > make INCDIRGMP=/usr/gnu/include \
                       LIBDIRGMP=/usr/gnu/lib/ dec-mips-ultrix-gcc2
    |\#| you will see a lot of messages |

Now repeat the compilation  for the NeXTstation. *Do not* forget to clean
up.

|    gap@tiffy:../ve > mv bin/me.exe bin/me.dec
    gap@tiffy:../ve > mv bin/qme.exe bin/qme.dec
    gap@tiffy:../ve > rlogin bjerun
    gap@bjerun:~ > cd gap3r4p0/pkg/ve
    gap@bjerun:../ve > make clean
    |\#| you will see some messages
    gap@bjerun:../ve > make next-m68k-mach-gcc2
    |\#| you will see a lot of messages
    gap@bjerun:../ve > mv bin/me.exe bin/me.next
    gap@bjerun:../ve > mv bin/qme.exe bin/qme.next
    gap@bjerun:../ve > exit
    gap@tiffy:../ve > |

Switch into the  subdirectory 'bin/' and  create scripts which will call
the correct binary for each machine.  The shell scripts that are already
contained in `bin/me.sgl` and `bin/qme.sgl` are suitable only for a single
architecture installation.

|    gap@tiffy:../ve > cat > bin/me
    |\#|!/bin/csh
    switch ( `hostname` )
      case 'bert':
      case 'tiffy':
        exec $0.dec $* ;
        breaksw ;
      case 'bjerun':
        exec $0.next $* ;
        breaksw ;
      default:
        echo "me/qme/zme: sorry, no executable exists for this machine" ;
        breaksw ;
    endsw
    |<ctr>-'D'|
    gap@tiffy:../ve > chmod 755 bin/me
    gap@tiffy:../ve > ln bin/me bin/qme |

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Weyl Package}

There is a  collection  of programs for  dealing with finite Weyl groups,
associated (Iwahori-) Hecke algebras, and their  representations.   These
programs  were  written  by Meinolf Geck (Lehrstuhl D \fuer\  Mathematik,
RWTH   Aachen,   Templergraben   64,  5100   Aachen,   Germany,  e-mail\:
geck@tiffy.math.rwth-aachen.de).

On a  low  level, these programs provide  the basic  data about  a  fixed
finite  Weyl  group $W$\: \\
having  specified a  Cartan matrix,  they compute  the  root system,  the
reflection representation, and the permutation representation on the root
vectors.   Elements of $W$  can be  given either as  permutations  or  as
reduced words  in  the standard generators  (i.e.,  simply as a  list  of
integers labelling the  generators), and there are  functions  to convert
these expressions  into  each other.   In  particular,  all functions  of
{\GAP} for working with permutation groups can be applied.

On  a  higher  level,  it  is  possible  to  compute distinguished  coset
representatives and  representatives  of the conjugacy  classes of $W$ of
minimal  length.   Furthermore,  there   are  functions  for  calculating
Kazhdan-Lusztig   polynomials,   left   cells,  and   the   corresponding
representations of the associated  Hecke algebra $H$  (for groups of rank
$\leq$  5, say).  Also,  computations inside  $H$ are  possible, such  as
multiplying two arbitrary elements of $H$ and  expressing the result as a
linear combination in the basis elements $T_w$, $w \in W$.

The following section describes the installation of  the Weyl package,  a
description  of the functions available in the Weyl  package is  given in
chapter "Weyl Groups and Hecke Algebras".

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installing the Weyl Package}

The  Weyl package  is completely written  in the {\GAP} language, it does
not require any additional programs  and/or compilations.  It will run on
any  computer that runs {\GAP}.  In the  following  we  will describe the
installation under  UNIX. The installation on the  Atari ST, TT or IBM PC
is similar.

If you  got a complete source distribution,  nothing has to be done.

In the example  we give we  will assume that {\GAP}  is installed  in the
home directory of a pseudo  user  'gap' and that you, as user 'gap', want
to install  the Weyl package.  Note that certain  parts of the  output in
the examples should only be taken as rough outline, especially file sizes
and file dates are *not* to be taken literally.

First  of all you have  to get the file   'weyl.zoo' (see "Getting GAP").
Then you must locate the {\GAP} directories containing 'lib/' and 'doc/',
this is usually 'gap3r4p0' where '0' is to be replaced by the current the
patch level.

|    gap:~ > ls -l
    drwxr-xr-x  11 gap      gap          1024 Nov  8  1991 gap3r4p0
    -rw-r--r--   1 gap      gap         35870 Nov 26 12:33 weyl.zoo
    gap:~ > ls -l gap3r4p0
    drwxr-xr-x   2 gap      gap          3072 Nov 26 11:53 doc
    drwxr-xr-x   2 gap      gap          1024 Nov  8  1991 grp
    drwxr-xr-x   2 gap      gap          2048 Nov 26 09:42 lib
    drwxr-xr-x   2 gap      gap          2048 Nov 26 09:42 src
    drwxr-xr-x   2 gap      gap          1024 Nov 26 09:42 tst|

Unpack the package using  'unzoo' (see "Installation  of GAP  for UNIX").
Note that you  must be in the directory  containing 'gap3r4p0'  to unpack
the  files.  After  you  have  unpacked the  source  you  may remove  the
*archive-file*.

|    gap:~ > unzoo x weyl.zoo
    gap:~ > ls -l gap3r4p0/pkg/weyl
    -rw-r--r--   1 gap      gap          1536 Nov 22 04:16 README
    -rw-r--r--   1 gap      gap         57058 Nov 22 04:02 init.g
    -rw-r--r--   1 gap      gap         40304 Nov 22 04:18 weyl.tex
    -rw-r--r--   1 gap      gap         57058 Nov 22 03:41 weylgrp.g|

If  the documentation  is not already  installed or  an older version  is
installed, copy  the file 'weyl.tex'  into  the 'doc/' directory  and run
latex  again (see   "Installation  of GAP   for UNIX").  In   general the
documentation   will  already be   installed so  you    can just skip the
following step.

|    gap:~ > cd gap3r4p0/pkg/weyl
    gap:../weyl > cp weyl.tex ../../doc
    gap:../weyl > cd ../../doc
    gap:../doc > latex manual
    # a few messages about undefined references
    gap:../doc > latex manual
    # a few messages about undefined references
    gap:../doc > makeindex manual
    # 'makeindex' prints some diagnostic output
    gap:../doc > latex manual
    # there should be no warnings this time |

Now  it  is  time  to  test  the installation.  Let  us  assume that  the
executable of {\GAP} lives in 'src/' and is called 'gap'.

|    gap:~/gap3r4p0 > src/gap -b
    gap> ?CartanMat
    CartanMat ____________________________ Weyl Groups and Hecke Algebras

    'CartanMat( <type>, <n> )'

    returns the Cartan matrix of Dynkin type <type> and rank <n>.

        gap> CartanMat( "F", 4 );
        [ [  2, -1,  0,  0 ],
          [ -1,  2, -1,  0 ],
          [  0, -2,  2, -1 ],
          [  0,  0, -1,  2 ] ]

    This function requires the package  "weyl"  (see "RequirePackage").

    gap> RequirePackage( "weyl" );
    gap> CartanMat( "F", 4 );
    [ [ 2, -1, 0, 0 ], [ -1, 2, -1, 0 ], [ 0, -2, 2, -1 ],
      [ 0, 0, -1, 2 ] ] |

If 'RequirePackage'  signals  an  error  check  the  permissions  of  the
subdirectories 'pkg/' and 'weyl/'.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\def\XGap{{\sf XGap}}
\Section{The XGap Package}

{\XGap} is an experimental graphical user interface for {\GAP}.  The only
supported window  system  at the  moment   is  X-Windows 11R5,   however,
programs  written for {\XGap} will run  on other platforms  as soon as an
user interface is available on these platforms.

Right now, no documentation is available, manual entries are delivered as
soon as the system is stable.  If you want to play with {\XGap} try

|    fceller@tiffy:~ > xgap
    gap> GraphicLattice( Group( (1,2,3,4), (1,3) ), 400, 600 );;
    gap> s := GraphicSheet( "Hallo World", 300, 300 );;
    gap> c := Circle( s, 100, 100, 50 );;
    gap> c.operations.MoveDelta( c, 10, 10 );
    gap> for i  in [ 1 .. 10 ]  do
    > c.operations.MoveDelta( c, i, -i );
    > od;
    gap> Delete( s, c );
    gap> Close(s); |

Please send comments, bug reports, etc. to

|    fceller@math.rwth-achen.de|
or
|    gap-trouble@math.rwth-aachen.de|


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installing the XGap Package}

{\XGap} is written in C and the package can only  be installed under UNIX
running  X-Windows  11R5.  It  has been  tested   on a DECstation running
Ultrix, a  SUN running  SunOS, a  PC  running  386bsd, and  a NeXTstation
running NeXTSTEP 3.0 and MouseX.

If you got a complete binary and source distribution for your machine, no
compilation is necessary,  you  must  however  adapted the  shell  script
'gap3r4p0/pkg/xgap/bin/xgap'.

If you  got a complete source distribution,  skip the  extraction part of
this section and proceed with the compilation part below.

In the example we will assume that you, as user 'gap', are installing the
{\XGap} package for use by several users on a network of two DECstations,
called 'bert'  and 'tiffy'. We  assume  that {\GAP} is also  installed on
these  machines following the  instructions given in "Installation of GAP
for UNIX".

Note that certain parts  of  the  output  in the examples should  only be
taken as rough outline, especially file sizes and file dates are *not* to
be taken literally.

First of  all you have  to get the file  'xgap.zoo' (see  "Getting GAP").
Then you  must locate the {\GAP}  directory containing 'lib/' and 'doc/',
this is usually  'gap3r4p0' where '0' is  to  be replaced  by the current
patch level.

|    gap@tiffy:~ > ls -l
    drwxr-xr-x  11 gap     1024 Nov  8  1991 gap3r4p0
    -rw-r--r--   1 gap   360891 Dec 27 15:16 anupq.zoo
    gap@tiffy:~ > ls -l gap3r4p0
    drwxr-xr-x   2 gap     3072 Nov 26 11:53 doc
    drwxr-xr-x   2 gap     1024 Nov  8  1991 grp
    drwxr-xr-x   2 gap     2048 Nov 26 09:42 lib
    drwxr-xr-x   2 gap     2048 Nov 26 09:42 pkg
    drwxr-xr-x   2 gap     2048 Nov 26 09:42 src
    drwxr-xr-x   2 gap     1024 Nov 26 09:42 tst|

Unpack the package  using 'unzoo' (see "Installation  of GAP for  UNIX").
Note that you must  be in the directory  containing 'gap3r4p0' to  unpack
the files.   After  you have  unpacked  the  source  you may  remove  the
*archive-file*.

|    gap@tiffy:~ > unzoo x xgap
    gap@tiffy:~ > ls -l gap3r4p0/pkg/xgap
    -rw-rw-rw-   1 gap  120  4401 Oct 18 12:12 Makefile
    drwxr-xr-x   2 gap  120   512 Oct 21 11:28 bin
    drwxr-xr-x   3 gap  120   512 Oct 18 12:06 lib
    drwxr-xr-x   3 gap  120   512 Oct 21 11:29 src
    drwxr-xr-x   2 gap  120   512 Apr 19  1993 tst|

Switch into the directory  'gap3r4p0/pkg/xgap/src/' and type 'make'. Note
that we do *not* supply an 'Imakefile'.

|gap@tiffy:~ > cd gap3r4p0/pkg/xgap/src
gap@tiffy:../src > make
usage: 'make <target>' where target is one of
'next-m68k-mach-gcc2'  for NeXT under Mach with X11R5 and GNU cc 2
'ibm-i386-386bsd-gcc2' for IBM PCs under 386BSD with X386 and GNU cc 2
'dec-mips-ultrix-gcc2' for DECstations under Ultrix with X11R5 and GNU cc 2
'dec-mips-ultrix-cc'   for DECstations under Ultrix with X11R5 and cc
'sun-sparc-sunos-cc'   for SUN SPARC under SunOS with X11R5 and cc
'sun-sparc-sunos-gcc'  for SUN SPARC under SunOS with X11R5 and GNU cc 2

    if the X11 include files directory does not live in
    "/usr/include",  you must set 'X11INC' to point to
    the correct directory

    if the X11 library files do not live in "/usr/lib",
    you must set 'X11LIB' to point to the correct directory |

Select the target you need.  In our case we use 'dec-mips-ultrix-gcc2' in
order to compile the DECstation version.

|    gap@tiffy:../src > make dec-mips-ultrix-gcc2
    # you will see a lot of messages |

This create  a executable 'xgap'   in the current directory.   If  {\GAP}
lives in the directory '~gap/gap3r4p0/src/gap' try the following:

|    gap@tiffy:../src > ./xgap -G ~gap/gap3r4p0/src/gap|

This command should create a new window in  which {\GAP} is awaiting your
input, type 'quit;' inside this window.  Strip the executable and move it
into the directory 'bin/', but *do not* call it 'xgap'.

|    gap@tiffy:../src > strip xgap
    gap@tiffy:../src > mv xgap ../bin/xgap-dec-mips-ultrix |

Switch into the directory 'bin/' and adapted the shell script 'xgap', you
must at  least  set the environment  variables  'EXEC', 'LIB', 'DOC', and
'GAP', where   'EXEC' should point   to your newly  created executable of
{\XGap}, 'LIB' should (after the first semicolon)  point to the directory
where {\GAP}\'s  libraries files live (it  *must*  end with a  '/'), 'DOC'
should point to the directory containing  the TeX files, and 'GAP' should
point to the executable of {\GAP}.




