The ``Advanced Coset Enumerator'' ACE:
ACE coset enumerator (C) 1995-2001 by George Havas and Colin Ramsayhttp://staff.itee.uq.edu.au/havas
can be called from within GAP through an interface, written by Alexander Hulpke and Greg Gamble, which is described in this manual.
The interface links to an external binary and therefore is only usable under UNIX (see Section Installing the ACE Package for how to install ACE). It will not work on Windows. The current version requires at least GAP 4.4. Users who still have GAP 4.3, must use ACE 4.1. (The first versions supported GAP 4.2.) ACE can be used through this interface in a variety of ways:
Each of these ways gives the user access to a welter of options, which are discussed in full in Chapters Options for ACE and Strategy Options for ACE. Yet more options are provided in Appendix Other ACE Options, but please take note of the Appendix's introductory paragraph. Check out Appendix Examples for numerous examples of the ACE commands.
Note: Some care needs to be taken with options; be sure to read Section General Warnings regarding the Use of Options and the introductory sections of Chapter Options for ACE for some warnings regarding them and a general discussion of their use, before using any of the functions provided by this interface to the ACE binary.
After loading ACE (see Section Loading the ACE Package),  if  you
want to use the ACE coset enumerator as a  default  for  all  coset
enumerations done by GAP (which may also  get  called  indirectly),
you can achieve this  by  setting  the  global  variable  TCENUM  to
ACETCENUM.
gap> TCENUM:=ACETCENUM;;
This    sets    the    function    CosetTableFromGensAndRels    (see
Section Coset  Tables  and  Coset  Enumeration  in  the   GAP
Reference Manual) to be  the  function  ACECosetTableFromGensAndRels
(described in Section Using ACE Directly to Generate a Coset Table),
which then can be called with all the options defined for  the  ACE
interface, not just the options max and silent. If TCENUM is set
to ACETCENUM without any  further  action,  the  default  strategy
(option) of the ACE enumerator will be used (see  Chapter Strategy Options for ACE).
You can switch back to the coset  enumerator  built  into  the  GAP
library by assigning TCENUM to GAPTCENUM.
gap> TCENUM:=GAPTCENUM;;
If, on the other hand you do not want to set up  ACE  globally  for
your coset enumerations, you may call the ACE  interface  directly,
which will allow you to decide for yourself, for each such call, which
options you want to use for running ACE. Please note  the  warnings
regarding options in Section General Warnings regarding  the  Use  of Options. The functions discussed in this and  the  following  section
(ACECosetTableFromGensAndRels and ACEStats)  are  non-interactive,
i.e. by their use, a file with your  input  data  in  ACE  readable
format will be handed to ACE and you will get the  answer  back  in
GAP format. At that moment however the ACE  job  is  terminated,
that is, you cannot send any further questions or requests  about  the
result of that job to ACE. For an interactive use  of  ACE  from
GAP see Section Using ACE  Interactively  and  Chapter Functions for Using ACE Interactively.
Using the ACE interface directly to generate a coset table is done by either of
ACECosetTableFromGensAndRels( fgens, rels, sgens [: options] ) F
ACECosetTable( fgens, rels, sgens [: options] ) F
Here fgens is a list of free generators, rels a list of  words  in
these generators giving relators for a finitely presented  group,  and
sgens the list of subgroup generators, again expressed as  words  in
the free generators. All these are given in the standard GAP format
(see Chapter Finitely Presented Groups of the  GAP  Reference
Manual). Note that the 3-argument form  of  ACECosetTable  described
here is merely a synonym for ACECosetTableFromGensAndRels, and  that
ACECosetTable may be called in a different  way  in  an  interactive
ACE    session    (see    Sections Using    ACE     Interactively
and ACECosetTable!interactive).
Behind the colon any selection of the options available for the interface (see Chapters Options for ACE and Strategy Options for ACE) can be given, separated by commas like record components. These can be used e.g. to preset limits of space and time to be used, to modify input and output and to modify the enumeration procedure. Note that strategies are simply special options that set a number of the options, detailed in Chapter Options for ACE, all at once.
Please see Section General Warnings regarding the Use of Options for a discussion regarding global and local passing of options, and the non-orthogonal nature of ACE's options.
Each of ACECosetTableFromGensAndRels and ACECosetTable  calls  the
ACE binary and, if successful, returns a standard coset table, as a
GAP list of  lists.  At  the  time  of  writing,  two  coset  table
standardisations schemes were possible: lenlex and semilenlex (see
Section Coset Table Standardisation Schemes). The user  may  control
which standardisation scheme is used by selecting either the  lenlex
(see option  lenlex)  or  semilenlex   (see option   semilenlex)
option;  otherwise  (since  GAP 4.3)  the  table  is   standardised
according to GAP's the  value  of  CosetTableStandard  (which  by
default is lenlex; for GAP 4.2, the variable CosetTableStandard
didn't exist and the default standardisation scheme was semilenlex).
We provide  IsACEStandardCosetTable  (see IsACEStandardCosetTable)
to determine whether a table (list of lists) is standard  relative  to
GAP's default standardisation scheme, or with the  use  of  options
(e.g. lenlex or semilenlex) to another standardisation scheme.
If the determination of a coset table is unsuccessful, then one of the following occurs:
incomplete option  (see option  incomplete)  an
incomplete coset table is returned (as a list of lists), with zeros in
positions where valid coset numbers could not be determined; or
silent option (see option  silent),  fail  is
returned; or
break-loop  is  entered.  This  last   possibility   is
discussed in detail via the example that follows.
The example given  below  is  the  call  for  a  presentation  of  the
Fibonacci group F(2,7) for  which  we  shall  discuss  the  impact  of
various options in Section Fun with ACEExample. Observe that in  the
example, no options are passed,  which  means  that  ACE  uses  the
default strategy (see Chapter Strategy Options for ACE).
gap> F:= FreeGroup( "a", "b", "c", "d", "e", "x", "y");; gap> a:= F.1;; b:= F.2;; c:= F.3;; d:= F.4;; e:= F.5;; x:= F.6;; y:= F.7;; gap> fgens:= [a, b, c, d, e, x, y];; gap> rels:= [ a*b*c^-1, b*c*d^-1, c*d*e^-1, d*e*x^-1, > e*x*y^-1, x*y*a^-1, y*a*b^-1];; gap> ACECosetTable(fgens, rels, [c]);;
In computing  the  coset  table,  ACECosetTableFromGensAndRels  must
first do a coset enumeration (which is where ACE comes in!). If the
coset enumeration does not finish in the preset limits a  break-loop
is entered,  unless  the  incomplete  (see option  incomplete)  or
silent (see option silent) options is set. In  the  event  that  a
break-loop is entered, don't despair or be frightened  by  the  word
Error; by tweaking ACE's options via the SetACEOptions function
that becomes available in the break-loop and then  typing  return;
it may be possible to help ACE complete the coset enumeration  (and
hence successfully compute the coset table); if not, you will  end  up
in the break-loop again, and you can have another go (or quit;  if
you've had enough). The  SetACEOptions  function  is  a  no-argument
function; it's there purely to pass options (which, of course, are
listed behind a colon (:)  with  record  components  syntax).  Let's
continue the Fibonacci example above, redoing  the  last  command  but
with the option max := 2  (see option  max),  so  that  the  coset
enumeration has only two coset numbers to play with and hence is bound
to fail to complete, putting us in a break-loop.
gap> ACECosetTable(fgens, rels, [c] : max := 2); Error, no coset table ... the `ACE' coset enumeration failed with the result: OVERFLOW (a=2 r=1 h=1 n=3; l=5 c=0.00; m=2 t=2) called from <function "ACECosetTable">( <arguments> ) called from read-eval-loop Entering break read-eval-print loop ... try relaxing any restrictive options e.g. try the `hard' strategy or increasing `workspace' type: '?strategy options' for info on strategies type: '?options for ACE' for info on options type: 'DisplayACEOptions();' to see current ACE options; type: 'SetACEOptions(:<option1> := <value1>, ...);' to set <option1> to <value1> etc. (i.e. pass options after the ':' in the usual way) ... and then, type: 'return;' to continue. Otherwise, type: 'quit;' to quit to outer loop. brk> SetACEOptions(: max := 0); brk> return; [ [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ] ]
Observe how the lines  after  the  ``Entering  break  read-eval-print
loop'' announcement tell you exactly what to  do  (for  GAP  4.2
these  lines  are  instead   Info-ed   before   the   break-loop
announcement). At  the  break-loop  prompt  brk>  we  relaxed  all
restrictions on max (by re-setting it to 0) and typed  return;  to
leave the break-loop. The coset  enumeration  was  then  successful,
allowing the computation of what turned out  to  be  a  trivial  coset
table. Despite the fact that the eventual coset  table  only  has  one
line (i.e. there is exactly one coset number)  ACE  did  need  to
define more than 2 coset numbers. To  find  out  just  how  many  were
required before the final  collapse,  let's  set  the  InfoLevel  of
InfoACE (see SetInfoACELevel) to 2, so that the ACE enumeration
result is printed.
gap> SetInfoACELevel(2); gap> ACECosetTable(fgens, rels, [c]); #I INDEX = 1 (a=1 r=2 h=2 n=2; l=6 c=0.00; m=2049 t=3127) [ [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ] ]
The enumeration result line is the Info line  beginning  ``#I ''.
Appendix The Meanings of  ACE's  Output  Messages  explains  how  to
interpret such output messages from ACE. In particular, it explains
that t=3127 tells us that a total number  of  3127  coset  numbers
needed to be defined before the final  collapse  to  1  coset  number.
Using some of the many options that ACE provides, one  may  achieve
this  result  more  efficiently,  e.g. with   the   purec   strategy
(see option purec):
gap> ACECosetTable(fgens, rels, [c] : purec); #I INDEX = 1 (a=1 r=2 h=2 n=2; l=4 c=0.00; m=332 t=332) [ [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ] ]
ACE needs to define a total number of only  (relatively-speaking)
332 coset numbers before the final collapse to 1 coset number.
Notes: 
To initiate the coset enumeration,  the  start  option  (see option start) is quietly inserted after the user's supplied options,  unless
the user herself supplies one  of  the  enumeration-invoking  options,
which are: start, or one of its synonyms, aep  (see option  aep)
or rep (see option rep).
When  a  user  calls  ACECosetTable   with   the   lenlex   option
(see option  lenlex),  occasionally  it  is  necessary  to   enforce
asis=1 (see option asis), which may be counter to the  desires
of the  user.  The  occasions  where  this  action  is  necessary  are
precisely those for which, for the  arguments  gens  and  rels  of
ACECosetTable,   IsACEGeneratorsInPreferredOrder   would    return
false.
The non-interactive ACECosetTable and ACECosetTableFromGensAndRels
now use an iostream to communicate with the ACE binary in order  to
avoid filling up a temporary directory with an incomplete coset  table
in  the  case  where  an  enumeration  overflows.  This  is  generally
advantageous. However, on some systems, it may not be  advisable  to
repeatedly  call  ACECosetTable  or   ACECosetTableFromGensAndRels
(e.g. in a loop), since one may run out of the pseudo  ttys  used  for
iostreams. If you encounter this problem, consider using an adaptation
of  the  usage  of  the  interactive  forms  of  ACECosetTable   and
ACEStats                            (see ACECosetTable!interactive
and ACEStats!interactive), together with  ACEStart  initialisation
steps, that is sketched in the schema below. For the  following  code,
it  is  imagined  the  scenario  is  one  of  looping   over   several
possibilities of fgens, rels and sgens; the two special forms of
ACEStart used, allow one to continually re-use a single  interactive
ACE process (i.e. only one iostream is used).
# start the interactive ACE process with no group information
procId := ACEStart(0);
while expr do
 fgens := ...; rels := ...; sgens := ...;
 ACEStart(procId, fgens, rels, sgens : options);
 if ACEStats(procId).index > 0 then
  table := ACECosetTable(procId);
  ...
 fi;
od;
For an already calculated coset table, we provide the following function to determine whether or not it has been standardised.
IsACEStandardCosetTable( table [: option] ) F
returns true if table (a list of lists of  integers)  is  standard
according to GAP's default or  the  option  (either  lenlex  or
semilenlex)  standardisation  scheme,  or  false  otherwise.   See
Section Coset  Table  Standardisation   Schemes   for   a   detailed
discussion of the lenlex and semilenlex standardisation schemes.
Note:
Essentially, IsACEStandardCosetTable  extends  the  GAP  function
IsStandardized.
Users who wish their coset tables  to  use  ACECosetTable  with  the
lenlex    (see option     lenlex)     option,     which     causes
lenlex standardisation to occur at the ACE (rather  than  GAP)
level, should be aquainted with the following function.
IsACEGeneratorsInPreferredOrder( gens, rels ) F
returns true if gens, a list of free group generators, are  in  an
order which will  not  be  changed  by  ACE,  for  the  group  with
presentation ágens   | rels ñ, where  rels  is  a
list   of   relators   (i.e. words   in   the   generators    gens).
IsACEGeneratorsInPreferredOrder may also be called  in  a  different
way         for         interactive          ACE          processes
(see IsACEGeneratorsInPreferredOrder!interactive).
For a presentation with more than one generator, the  first  generator
of which is an involution and the second is  not,  ACE  prefers  to
switch the  first  two  generators.  IsACEGeneratorsInPreferredOrder
returns true if the order of the  generators  gens  would  not  be
changed  within  ACE  and  false,  otherwise.  (Technically,   by
``involution'' above, we really mean ``a generator x for which there
is a relator in rels of form x*x or x^2''. Such a generator may,
of course, turn out to actually be the identity.)
Guru Notes:
If  IsACEGeneratorsInPreferredOrder(gens,  rels)  would   return
false, it is possible to enforce a user's order  of  the  generators
within ACE, by setting the option asis (see option asis)  to  1
and, by passing the relator that determines that gens[1] (which we
will assume is x) has order  at  most  2,  as:  x*x  (rather  than
x^2).  Behind  the  scenes  this  is  precisely  what  is  done,  if
necessary, when ACECosetTable is called with the lenlex option.
The user may avoid all the technicalities  by  either  not  using  the
lenlex option (and allowing GAP to  take  care  of  the  lenlex
standardisation), or by swapping the first  two  generators  in  those
cases where  IsACEGeneratorsInPreferredOrder(gens,  rels)  would
return false.
If you only want to test, whether a coset enumeration terminates, and don't want to transfer the whole coset table to GAP, you can call
ACEStats( fgens, rels, sgens [: options] ) F
which calls ACE non-interactively to do the coset enumeration, the result of which is parsed and returned as a GAP record with fields
index 
cputime cputimeUnits (the next field);
cputimeUnits cputime  field,  e.g. "10^-2
seconds";
activecosets maxcosets totcosets 
Options (see Chapters Options  for  ACE  and Strategy  Options  for ACE)   are   used    in    exactly    the    same    way    as    for
ACECosetTableFromGensAndRels, discussed in the previous section; and
the same  warnings  alluded  to  previously,  regarding  options  (see
Section General Warnings regarding the Use of Options), apply.
Notes:
To initiate the coset enumeration,  the  start  option  (see option start) is quietly inserted after the user's supplied options,  unless
the user herself supplies one  of  the  enumeration-invoking  options,
which are: start, or one of its synonyms, aep  (see option  aep)
or rep (see option rep).
The fields of the  ACEStats  record  are  determined  by  parsing  a
``results  message''  (see  Appendix The  Meanings  of  ACE's  Output Messages) from ACE.
ACEStats may also be called in a different  way  in  an  interactive
ACE session (see ACEStats!interactive).
If you want to use ACE as a standalone with its own syntax, you can
write an ACE standalone input file by calling ACECosetTable  with
three arguments (see ACECosetTableFromGensAndRels)  and  the  option
aceinfile := filename (see option aceinfile). This will keep the
input file for the ACE standalone produced by the GAP  interface
under the file name filename (and  just  return)  so  that  you  can
perform interactive work in the standalone.
An interactive ACE process is initiated with the command
ACEStart( fgens, rels, sgens [:options] ) F
whose    arguments    and    options    are     exactly     as     for
ACECosetTableFromGensAndRels  and  ACEStats,   as   discussed   in
Sections Using ACE Directly to Generate a Coset Table and Using ACE Directly to Test whether a Coset Enumeration  Terminates.  The  usual
warnings  regarding  options  apply  (see  Section General   Warnings regarding the Use of Options). ACEStart has a number of other forms
(see ACEStart!details).
The return value is an integer (numbering from 1) which represents the running process. (It is possible to have more than one interactive process running at once.) The integer returned may be used to index which of these processes an interactive ACE function should be applied to.
An interactive ACE process is terminated with the command
ACEQuit( i ) F
where i is the integer returned by ACEStart when the  process  was
begun.   ACEQuit   may   also   be   called   with   no    arguments
(see ACEQuit!details).
We discuss each of these commands, as well as the range of functions which enable one to access features of the ACE standalone not available non-interactively, in depth, in Chapter Functions for Using ACE interactively.
Note:
ACE not only allows one to do a coset enumeration of a group  by  a
given (and then fixed) subgroup but it also allows one to  search  for
subgroups by starting from a given one (possibly the trivial subgroup)
and then augmenting  it  by  adding  new  subgroup  generators  either
explicitly               via                ACEAddSubgroupGenerators
(see ACEAddSubgroupGenerators)   or   implicitly   by    introducing
coincidences (see ACECosetCoincidence:  ACECosetCoincidence,  or
ACERandomCoincidences: ACERandomCoincidences);  or  one  can  find
smaller   subgroups    by    deleting    subgroup    generators    via
ACEDeleteSubgroupGenerators (see ACEDeleteSubgroupGenerators).
There are a number of examples available in the examples  directory,
which may be accessed via
ACEExample() F
ACEExample( examplename [:options] ) F
ACEExample( examplename, ACEfunc [:options] ) F
where  examplename  is  a  string,  the  name  of  an  example  (and
corresponding file in the examples directory); and ACEfunc is  the
ACE function with which the example is to be executed. 
If ACEExample is called with no arguments,  or  with  the  argument:
"index" (meant in the sense of ``list''),  or  with  a  non-existent
example  name,  a  list  of  available  examples  is  displayed.   See
Section Fun with ACEExample where the list is displayed.
By  default,  examples  are  executed  via  ACEStats.  However,   if
ACEExample is called with a second argument (choose from the (other)
alternatives:   ACECosetTableFromGensAndRels    (or,    equivalently
ACECosetTable), or ACEStart), the example is executed  using  that
function, instead. Note that, whereas the first  argument  appears  in
double quotes (since it's a string),  the  second  argument  does  not
(since it's a function); e.g. to execute example "A5" with  function
ACECosetTable, one would type: ACEExample("A5", ACECosetTable);.
ACEExample also accepts user options, which  may  be  passed  either
globally  (i.e. by  using  PushOptions  to  push   them   onto   the
OptionsStack) or locally  behind  a  colon  after  the  ACEExample
arguments, and they are passed to ACEStats or ACEfunc as  if  they
were appended to the existing options of examplename; in this way,
the user may over-ride any or all of the options  of  examplename.
This is done by passing  an  option  aceexampleoptions  (see option aceexampleoptions), which sets up a mechanism to  reverse  the  usual
order in which options of recursively called functions are pushed onto
the OptionsStack. The option aceexampleoptions  is  not  a  user
option; it is intended only for internal use  by  ACEExample,  for
the above purpose. In the portion of the  output  due  to  the  echo
option, if one has  passed  options  to  ACEExample,  one  will  see
aceexampleoptions listed first and the result of the interaction  of
examplename's options and the additional options.
Consider the example "A5". The effect of running
gap> ACEExample("A5", ACEStart);
is essentially equivalent to executing:
gap> file := Filename(DirectoriesPackageLibrary("ace", "examples"), "A5");;
gap> ACEfunc := ACEStart;;
gap> ReadAsFunction(file)();
except that some internal ``magic'' of ACEExample edits the  example
file and displays equivalent commands a user ``would'' execute. If the
user  has  passed  options  to  ACEExample   these   appear   in   a
``# User Options'' block after the original options of the  example
in the Info portion of the output. By comparing with the portion  of
the output from the echo option (unless the user has over-ridden the
echo option), the user may directly observe any over-riding  effects
of user-passed options.
Please see Section Fun with ACEExample for some sample  interactions
with ACEExample.
Notes
Most examples use the mess  ( = messages)  option.  To  see  the
effect of this, it is recommended to do: SetInfoACELevel(3);  before
calling ACEExample, with an example.
The coset table output from ACEExample, when called with many of the
examples and with the ACE  function  ACECosetTableFromGensAndRels
is often quite long. Recall that  the  output  may  be  suppressed  by
following the (ACEExample) command with a double semicolon (;;).
Also, try SetInfoACELevel(2); before  calling ACEExample, with  an
example.
If you unexpectedly observe aceexampleoptions in your  output,  then
most probably you have unintentionally passed options  by  the  global
method, by having a non-empty OptionsStack. One possible  remedy  is
to use FlushOptionsStack(); (see FlushOptionsStack), before trying
your ACEExample call again.
As discussed in Section Interpretation  of  ACE  Options,  there  is
generally no sensible meaning that can  be  attributed  to  setting  a
strategy option (see Chapter Strategy Options for ACE)  to  false;
if you wish to nullify the effect of a strategy option,  pass  another
strategy  option,  e.g. pass  the  default  (see option   default)
strategy option.
Also provided are:
ACEReadResearchExample( filename ) F
ACEReadResearchExample() F
which perform Read (see Section Read in the  GAP  Reference
Manual) on filename or, with no argument,  the  file  with  filename
"pgrelfind.g" in the res-examples directory;  e.g. the  effect  of
running
gap> ACEReadResearchExample("pgrelfind.g");
is equivalent to executing:
gap> Read( Filename(DirectoriesPackageLibrary("ace", "res-examples"),
>                   "pgrelfind.g") );
The examples provided in the res-examples  directory  were  used  to
solve a genuine research problem, the results of which are reported in
CHHR01. Please see Section Using  ACEReadResearchExample  for
a detailed description and examples of its use.
ACEPrintResearchExample( example-filename ) F
ACEPrintResearchExample( example-filename, output-filename) F
print the ``essential'' contents of the file example-filename in the
res-examples directory to the terminal, or with two arguments to the
file  output-filename;  example-filename   and   output-filename
should be strings. ACEPrintResearchExample is provided  to  make  it
easy for users to copy and edit the examples for their own purposes.
Firstly, let us mention (and we will remind you later) that an ACE strategy is merely a special option of ACE that sets a number of the options described in Chapter Options for ACE all at once. The strategy options are discussed in their own chapter (Chapter Strategy Options for ACE).
In Section Passing ACE Options, we describe the two  means  provided
by GAP by which ACE options may be passed. In  Section Warnings regarding Options, we discuss how options ``left over'' from previous
calculations can upset subsequent calculations; and hence, to  ``clear
the  decks''   in   such   circumstances,   why   we   have   provided
FlushOptionsStack   (see FlushOptionsStack).   However,   removing
OptionsStack options does not remove the options  previously  passed
to  an  interactive  ACE  process;  Section Warnings   regarding Options discusses that too.
Note,  that  the  ACE  package   treatment   of   options   is   an
``enhancement'' over the general way GAP treats  options.  Firstly,
the ACE binary allows abbreviations and mixed case of  options  and
so  the  ACE  package  does  also,   as   much   as   is   possible
(see Abbreviations and mixed case for ACE Options). Secondly,  since
ACE's options are in general not orthogonal,  the  order  in  which
they are put to ACE is, in general, honoured (see Honouring of the order in which ACE Options are passed). Thirdly, the ACE  binary's
concept of a boolean option is slightly different to that of GAP's;
Section Interpretation of ACE Options discusses, in particular,  how
an option detected by GAP as true is passed to the ACE binary.
Finally, Section What happens if no ACE Strategy Option or if no ACE Option is passed discusses what happens if no option is selected.
ACEData V
is a GAP record in which the essential data for an ACE session within GAP is stored; its fields are:
binary 
tmpdir 
ni     
io     ACEStart   (see  below 
and ACEStart) processes;
infile 
outfile
versionACEBinaryVersion (see ACEBinaryVersion).
Non-interactive processes used to use files rather than streams (hence
the fields infile and outfile above;  these  may  disappear  in  a
later version of the ACE package).
Each time an interactive ACE process is  initiated  via  ACEStart
(see ACEStart), an identifying number ioIndex is generated for the
interactive process and  a  record  ACEData.io[ioIndex]  with  the
following fields is created. A  non-interactive  process  has  similar
fields but is stored in the record ACEData.ni.
procId 
args   fgens, rels,  sgens  whose
values  are  the  corresponding   arguments   passed   originally   to
ACEStart;
options
acegensACEStart were all lowercase alphabetic  characters,  then
acegens is the String equivalent of fgens,  i.e. acegens[1]   =
String(fgens[1]) etc.);
stream ACEStart; and
enumResult 
stats  ACEStats.
enforceAsis true  whenever  the   asis   option
(see option asis) must  be  set  to  1.  It  is  usually  false.
See IsACEGeneratorsInPreferredOrder Guru Notes for the details.
ACEDirectoryTemporary( dir ) F
calls the UNIX command mkdir  to  create  dir,  which  must  be  a
string, and if  successful  a  directory  object  for  dir  is  both
assigned to ACEData.tmpdir and returned. The fields ACEData.infile
and ACEData.outfile are also set to be  files  in  ACEData.tmpdir,
and on exit from GAP dir is removed. Most users will  never  need
this command;  by  default,  GAP  typically  chooses  a  ``random''
subdirectory of /tmp for  ACEData.tmpdir  which  may  occasionally
have limits on what  may  be  written  there.  ACEDirectoryTemporary
permits the user to choose a directory (object) where one  is  not  so
limited.
InfoACE V
The output of the ACE binary is, by default, not displayed. However
the user may choose to see some, or all, of this output. This is  done
via the Info mechanism  (see  Chapter Info  Functions  in  the
GAP Reference Manual). For this purpose, there is  the  InfoClass
InfoACE. Each line of output from ACE is directed to  a  call  to
Info and will be displayed for the user to see if the InfoLevel of
InfoACE is high enough. By default, the InfoLevel of InfoACE  is
1, and it is recommended that you leave it at this level,  or  higher.
Only messages which we think that the user will really want to see are
directed to Info at InfoACE level 1. To turn off  all  InfoACE
messaging, set the InfoACE level to 0  (see SetInfoACELevel).  For
convenience, we provide the function
InfoACELevel() F
which returns the current InfoLevel of InfoACE, i.e. it is  simply
a shorthand for InfoLevel(InfoACE).
To set the InfoLevel of InfoACE we also provide
SetInfoACELevel( level ) F
SetInfoACELevel() F
which for a non-negative integer  level,  sets  the  InfoLevel  of
InfoACE    to    level    (i.e. it    is    a    shorthand     for
SetInfoLevel(InfoACE, level)),  or  with  no  arguments  sets  the
InfoACE level to the default value 1.  Currently,  information  from
ACE is directed to Info at four InfoACE levels: 1, 2, 3 and  4.
The command
gap> SetInfoACELevel(2);
enables the display of the results line of an enumeration from ACE, whereas
gap> SetInfoACELevel(3);
enables the display of  all  of  the  output  from  ACE  (including
ACE's  banner,  containing  the  host  machine   information);   in
particular,  the  progress  messages,  emitted  by  ACE  when   the
messages option (see option messages) is set to a non-zero  value,
will be displayed via Info. Finally,
gap> SetInfoACELevel(4);
enables the display of all the input  directed  to  ACE  (behind  a
``ToACE> '' prompt, so you can distinguish it  from  other  output).
The InfoACE level of 4 is really for gurus who are familiar with the
ACE standalone.
Large parts of this manual,  in  particular  the  description  of  the
options for running ACE, are directly copied  from  the  respective
descriptions in the manual Ram99ace for the standalone version  of
ACE by Colin Ramsay.  Most  of  the  examples,  in  the  examples
directory and accessed  via  the  ACEExample  function,  are  direct
translations of Colin Ramsay's  test###.in  files  in  the  src
directory.
Many thanks to Joachim Neubüser who not only provided one of the early manual drafts and hence a template for the style of the manual and conceptual hooks for the design of the Package code, but also meticulously proof-read all drafts and made many insightful comments.
Many thanks also to Volkmar Felsch who, in testing the ACE Package,
discovered a number of bugs, made a number of important suggestions on
code improvement, thoroughly checked all the  examples,  and  provided
the example found at the end of Section Steering  ACE  Interactively
which  demonstrates  rather  nicely  how  one  can  use  the  function
ACEConjugatesForSubgroupNormalClosure.
We  also  wish  to  acknowledge the contribution of Charles Sims.  The
inclusion of the incomplete (see option incomplete)  and  lenlex
(see option lenlex) options, were made in response  to  requests  to
the  GAP  developers  to  include  such  options  for  coset  table
functions. Also, the definition of lenlex standardisation  of  coset
tables (see Section Coset Table Standardisation Schemes), is due  to
him.
Finally, much of the work since 2005 in modifying the  ACE  package
particularly for new versions of GAP and in getting ACE  to  its
new home on GitHub has been due to Max Horn.
A reasonably comprehensive history of  the  evolution  of  pre-release
versions of the ACE Package, is contained in the file CHANGES  in
the gap directory. 
The 3.xxx versions of the ACE Package were compatible with GAP
4.2, but were built for use with  GAP  4.3.  However,  the  current
version of the ACE Package requires at least GAP 4.4. Users  who
still have GAP 4.3 will need  to  use  ACE  4.1.  One  important
change in GAP from GAP 4.2 to GAP 4.3 that has relevance  for
ACE Package users is the change of the  default  standard  for  the
numbering of  cosets  in  a  coset  table  (see  Section Coset  Table Standardisation Schemes).
ACEPackageVersion() F
gives the current version of the ACE Package (i.e. the GAP  code
component; the  function  ACEBinaryVersion  (see ACEBinaryVersion)
gives details of the C code compilation).
History of release versions
3.001
3.002ACEIgnoreUnknownDefault (see ACEIgnoreUnknownDefault)  added.
continue  changed  to  continu  (see option  continu)  --
continue is a keyword in GAP 4.3.
3.003ACEIgnoreUnknownDefault is now  true  (previously
it was false).
ACECosetTableFromGensAndRels and the non-interactive ACECosetTable
(except when producing an input script via  option  ACEinfile),  and
the non-interactive ACEStats which previously  used  files  all  now
invoke iostreams.
pkgbanner used to control  the  printing  of  the  banner  on
loading (see Loading the ACE Package).
4.0pkgbanner is no  longer
available (most of its function is now provided by the third  argument
of the LoadPackage function; see LoadPackage).
4.1res-examples/pgrelfind.g.
5.0pkgbanner has been completely removed.
5.1configure and Makefile.in were made more robust to ensure
they will work well with both GAP 4.4 and GAP 4. At the advent of
GAP 4.5, which was about the time ACE 5.1  was  released,  option
order behind the colon was no longer respected, but went unnoticed.
5.2SetInfoACELevel(3) to tst/aceds.tst, so that the ERROR message
is visible. This mistake in the test file probably goes back to  version
4.0. Other changes are due to making the documentation  compatible  with
GAP 4.7 manuals and ACE's new home on GitHub and using git for
version control. Fixing the lack of respect  for the ordering of options 
is deferred to the next version of ACE.
ACE manual