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 current version of the ACE  package
is 5.0 (which interfaces with version 3.001 of the ACE C program 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; however, the current version requires at least GAP
4.4.

Version 5.0 of ACE removes all deprecated code, particularly with respect
to the package loading mechanism.  It  is  not  backward-compatible  with
pre-4.4 versions of GAP. If  you  are  still  using  GAP  4.3,  you  must
continues to use the previous version (4.1) of ACE.

You can download  `ace-XXX.zoo'  (where  `XXX'  is  the  package  version
number) from the home page for the ACE package

http://www.math.rwth-aachen.de/~Greg.Gamble/ACE/ (Germany)

or the Australian mirrors

http://www.maths.uwa.edu.au/~gregg/ACE/          (Perth, Australia)
http://www.itee.uq.edu.au/~gregg/ACE/            (Queensland, Australia)

or via the Packages links from the GAP sites

http://www.gap-system.org/                       (UK)
http://www.math.rwth-aachen.de/~GAP/             (Germany)

or the GAP ftp servers

ftp://ftp-gap.dcs.st-and.ac.uk/pub/gap/gap4/zoo/packages/
ftp://ftp.math.rwth-aachen.de/pub/gap4/zoo/packages/

If you prefer tar.gz or tar.bz2 to zoo  archives,  substitute  tar.gz  or
tar.bz2 (as appropriate) for zoo in the above paths.

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  a
pre-MacOSX 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

  LoadPackage("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  (view  either  `manual.dvi'  via  `xdvi'  or
`manual.ps' via `ghostview' or `manual.pdf'  via  a  PDF  viewer),  which
gives information on how to use ACE from within GAP. The ACE user  manual
(`ace3001.ps'  or  `ace3001.pdf')  in  the  `standalone-doc'   directory,
explains how to use the ACE binary (i.e. the C program that is interfaced
with by the package from within GAP) 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)
   gcc 2.95.3 20010315  Linux                 (release)
   gcc 2.95.4 20011002  Linux                 (Debian prerelease)
   gcc 2.96 20000731    Red Hat Linux 7.2     (2.96-112.7.2)
   gcc 3.2 20020903     Red Hat Linux 8.0     (3.2-7)

(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; 22 December, 2003; 26 January, 2006.