                               The ACE package

The ACE package provides functions associated with Todd-Coxeter  coset
enumeration by interfacing with the Advanced Coset Enumerator (ACE),

ACE coset enumerator (C) 1995-2001 by George Havas and Colin Ramsay
    http://www.itee.uq.edu.au/~cram/ce.html

from within GAP 4.

The GAP interface (package) has been written by Alexander  Hulpke  and
Greg Gamble. In order to install the ACE  package  you  must  get  the
archive file `ace-XXX.zoo', for  some  version  number  `XXX',  (which
includes the C source code of Havas and Ramsay).

The  ACE  package  provides  a  mechanism  to  replace   GAP's   usual
Todd-Coxeter coset enumerator by ACE, so that  functions  that  behind
the scenes use coset enumeration will use the ACE enumerator. The  ACE
enumerator may also be used  explicitly;  both  non-interactively  and
interactively. However the package is used, a plethora of options  and
strategies are available to assist the  user  in  avoiding  incomplete
coset  enumerations.  The  interactive  functions  provided  use   the
IOStream functionality first introduced in GAP 4.2.  (Hence,  the  ACE
package requires at least GAP 4.2.)

You can download `ace-XXX.zoo' (where `XXX'  is  the  package  version
number) from the same places as GAP. The main FTP servers are:

ftp://ftp-gap.dcs.st-and.ac.uk/pub/gap/gap4/share/
ftp://ftp.math.rwth-aachen.de/pub/gap4/share/
ftp://ftp.ccs.neu.edu/pub/mirrors/ftp-gap.dcs.st-and.ac.uk/pub/gap/gap4/share/

`ace-XXX.zoo' is also available via the GAP www page at

http://www-gap.dcs.st-and.ac.uk/~gap/Info4/share.html
http://aldebaran.math.rwth-aachen.de/~GAP/Info4/share.html
http://mirrors.ccs.neu.edu/GAP/NEU/Info4/share.html

or, alternatively, from one of the authors' home page at

http://www.itee.uq.edu.au/~gregg/ACE/home.html

Since the ACE package interfaces to an external  binary,  it  is  only
usable under UNIX or a UNIX-like environment.  It  will  not  work  on
Windows or the Macintosh.


                         Installing the ACE package

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

Then unzoo `ace-XXX.zoo' by

  unzoo -x ace-XXX

Go to the newly created `ace' directory and  call  `configure  <path>'
where <path> is the path to the GAP home directory. So for example  if
you install the package in the main `pkg' directory call

  ./configure ../..

This will fetch the architecture type for which GAP has been  compiled
last and create a `Makefile'. Now simply call

  make

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

Note that the current version of the configuration process  only  sets
up directory paths. If you need  a  different  compiler  or  different
compiler options, you need to edit `src/Makefile.in' prior to  calling
`make' yourself.

If you use this installation of GAP on  different  hardware  platforms
you will have to compile the binary for each platform separately. This
is done by  calling  `configure'  and  `make'  for  the  package  anew
immediately  after   compiling   GAP   itself   for   the   respective
architecture. If your version of GAP is already compiled (and has last
been compiled on the same architecture) you do not need to compile GAP
again, it is sufficient to call the `configure' script in the GAP home
directory.

That's it. Now start GAP and type

  RequirePackage("ace");

The ACE banner should appear on the screen.

For  details  on  how  to  use  the  ACE  package  see   the   package
documentation in the `doc' subdirectory (execute `make_doc'  and  then
view either `manual.dvi' via `xdvi' or `manual.ps'  via  `ghostview'),
which gives information on how to use ACE from within GAP, and the ACE
user manual (`ace3001.dvi' created by executing `latex ace3001'  three
times) in the `standalone-doc' directory, which gives  information  on
how to use the ACE binary as a stand-alone.

The `src' subdirectory contains a copy of the C source code  for  ACE.
The only modification are those listed in src/CHANGES. In particular,
the file `src/Makefile.in' from which `src/Makefile' is generated has
been added, and the following bug was fixed on 25 February, 2001.

A bug was discovered in ACE  3.000  on  22  December,  2000  that  was
particularly manifested by the Linux gcc compilers listed  below.  The
bug was reported with fix by Volker Gebhardt (thanks!)  and  caused  a
segmentation fault when ACE output coset representatives. The  fix  is
incorporated in ACE 3.001 which we now use.

ACE has been compiled successfully with the following C compilers:

   compiler             platform              comments
   --------             --------              --------
   gcc 2.7.2.1          Linux
   gcc 2.7.2.3          Linux
   gcc 2.8.1            Solaris 2.51/IRIX 6.5 
   cc MIPSpro 7.2.1     IRIX 6.5
   cc MIPSpro 7.3.1.1m  IRIX 6.5              (compiled with -64 = 64bit)
   gcc 2.91.66 19990314 Linux                 (egcs 1.1.2 release)
   gcc 2.95.2 19990906  Linux                 (prerelease)
   gcc 2.95.2 19991024  Solaris 2.51, 2.8     (release)
   gcc 2.95.2 20000220  Linux                 (release)

(Since April 1999, egcs has been the official Gnu cc supplier. This is
why the numbering now follows egcs' numbering.)

If you encounter problems with the ACE binary, please contact  one  of
the C code  authors:  George  Havas  <havas@itee.uq.edu.au>  or  Colin
Ramsay <cram@itee.uq.edu.au>.

If you encounter problems at the GAP level, please contact one of  the
ACE package authors: Greg Gamble <gregg@itee.uq.edu.au>  or  Alexander
Hulpke <hulpke@math.colostate.edu>.

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

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

  - Greg Gamble 
    Centre for Discrete Mathematics and Computing, 
    Department of Information Technology and Electrical Engineering,
    The University of Queensland,
    Brisbane, Queensland, 4072
    Australia
    e-mail: gregg@itee.uq.edu.au
    www:    http://www.itee.uq.edu.au/~gregg
  -- 30 April, 2002.
