# ACE

Version 5.2
Released 2016-03-11

This project is maintained by Greg Gamble, Max Horn

                              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://staff.itee.uq.edu.au/havas

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
e.g. ace-XXX.tar.gz', for some version  number XXX', (which includes the C
source code of Havas and Ramsay). The  current version of the ACE package is
5.2 (which interfaces with  version 3.001 of the ACE C  program of Havas and
Ramsay). This  version has mainly been  produced to include all  updates and
have HTML  manual links that work  with the GAPDoc-compiled versions  of the
main  GAP  4.7 manuals.  The  next  version ACE  5.3  will  fix a  bug  that
eventuated at  the time of ACE  5.1 with changes  to GAP brought in  for GAP
4.5: in order to  enforce the ordering of options put  to ACE functions, ACE
exploited an undocumented feature of GAP  record fields: up to GAP 4.4 their
ordering was fixed, but  since GAP 4.5 this has no longer  been the case. We
may also migrate to GAPDoc generated manuals in ACE 5.3.

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 removed all deprecated code, particularly with respect to
versions of GAP.  If you are still  using GAP 4.3, you must  continue to use
the previous version (4.1) of ACE.

You can download  ace-XXX.tar.gz'  (where  XXX'  is  the  package  version

http://gap-packages.github.io/ace/

or via the GAP web site

http://www.gap-system.org/Packages/ace.html

If you prefer .zip or tar.bz2 to tar.gz archives, substitute the appropriate
suffix in the  above paths. (Note that .zoo archives  haven't been supported
since GAP 4.5.)

Since the ACE package interfaces to an external binary, it is only usable in
an  environment that  supports compiling  of the  binary, e.g.  a UNIX  or a
UNIX-like environment.

Installing the ACE package

To install  the ACE package, move  the file ace-XXX.tar.gz' 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 unpack ace-XXX.tar.gz',  which in most Linux environments  can be done
by

tar zxf ace-XXX.tar.gz

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

./configure ../..

In fact ../..'  is the default path.  So, if this is correct,  you may omit
it. 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

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 compiler:

gcc version 4.8.4 (Ubuntu 4.8.4-2ubuntu1~14.04.1)

and is presumed to compile with any modern version of C compiler.

C code authors:  George  Havas    or  Colin  Ramsay
.

package authors: Greg Gamble  or Alexander Hulpke
.

When sending a bug report, remember we will need to be able to  reproduce

* 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
`