The user will probably benefit most from interactive use of ACE  by
setting   the   InfoLevel   of   InfoACE    to    at    least    3
(see SetInfoACELevel),  particularly  if  she  uses  the  messages
option with a non-zero value.
Have you read the various options warnings yet? If not, please take the time to read Section General Warnings regarding the Use of Options which directs you to various important sections of Chapter Options for ACE.
We describe in this chapter the functions that manipulate and initiate interactive ACE processes.
An  interactive  ACE  process  is  initiated  by   ACEStart   and
terminated  via  ACEQuit;   these   functions   are   described   in
Section Starting and Stopping Interactive ACE Processes.  ACEStart
also has forms that manipulate an already started  interactive  ACE
process. ACEStart always  returns  a  positive  integer  i,  which
identifies the  interactive  ACE  process  that  was  initiated  or
manipulated.
Most functions (there is one ACEStart exception), that manipulate an
already started interactive ACE process,  have  a  form  where  the
first  argument  is  the  integer  i  returned  by  the   initiating
ACEStart command, and a second form with one argument  fewer  (where
the integer i is  discovered  by  a  default  mechanism,  namely  by
determining the least integer i  for  which  there  is  a  currently
active interactive ACE process). We will  thus  commonly  say  that
``for the ith (or default) interactive  ACE  process''  a  certain
function performs a given action. In each case, it is an error, if i
is not the index of an active interactive process,  or  there  are  no
current active interactive processes.
Notes: 
The global method of passing options (via PushOptions),  should  not
be  used  with  any  of  the  interactive  functions.  In  fact,   the
OptionsStack should be empty at the  time  any  of  the  interactive
functions is called.
On quitting GAP, ACEQuitAll(); is  executed,  which  terminates
all active interactive ACE processes. If GAP is  killed  without
quitting, before all interactive ACE  processes  are  terminated,
zombie processes (still living  child  processes  whose  parents
have died), will result. Since zombie processes do consume  resources,
in such an event, the responsible computer user should  seek  out  and
kill the still living ace children (e.g. by piping the output  of  a
ps with appropriate options, usually aux or ef, to  grep  ace,
to find the process ids, and then using kill; try man ps and  man
kill if these hints are unhelpful).
ACEStart( fgens, rels, sgens [:options] ) F
ACEStart( i [:options] ) F
ACEStart( [:options] ) F
ACEStart( i, fgens, rels, sgens [:options] ) F
ACEStart( 0 [:options] ) F
ACEStart( 0, fgens, rels, sgens [:options] ) F
ACEStart( 0, i [:options] ) F
ACEStart( 0, i, fgens, rels, sgens [:options] ) F
The variables are: i, a positive integer numbering from 1 that represents (indexes) an already running interactive ACE process; fgens, a list of free generators; rels, a list of words in the generators fgens giving relators for a finitely presented group; and sgens, a list of subgroup generators, again expressed as words in the free generators fgens. Each of fgens, rels and sgens are given in the standard GAP format for finitely presented groups (See Chapter Finitely Presented Groups of the GAP Reference Manual).
All forms of ACEStart accept options described in  Chapters Options for ACE and Strategy  Options  for  ACE,  and  Appendix Other  ACE Options, which are listed behind  a  colon  in  the  usual  way  (see
Function Calls in the GAP Reference Manual).  The  reader  is
strongly   encouraged   to   read   the   introductory   sections   of
Chapter Options  for  ACE,  with  regard  to  options.  The   global
mechanism (via PushOptions) of passing options is not  recommended
for use with the interactive ACE interface functions; please ensure
the OptionsStack is  empty  before  calling  an  interactive  ACE
interface function. 
The  return  value  (for  all  forms  of  ACEStart)  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 interface function should be applied to.
The first four forms  of  ACEStart  insert  a  start  (see option start) directive after the user's options to invoke  an  enumeration.
The last four forms, with 0 as  first  argument,  do  not  insert  a
start directive. Moreover, the last 3 forms of ACEStart, with  0
as  first  argument  only  differ  from  the  corresponding  forms  of
ACEStart without the 0 argument, in that  they  do  not  insert  a
start directive. ACEStart(0),  however,  is  special;  unlike  the
no-argument form of ACEStart it invokes  a  new  interactive  ACE
process. We will now further describe each form of ACEStart, in  the
order they appear above.
The first form of ACEStart (on three arguments) is the usual way  to
start an interactive ACE process.
When ACEStart is called with one positive integer  argument  i  it
starts a new enumeration on the ith running process, i.e. it  scrubs
a previously generated table and starts from  scratch  with  the  same
parameters (i.e. the same arguments and options); except that  if  new
options are included these will modify  those  given  previously.  The
only reason for doing such a thing, without new options, is to perhaps
compare timings of runs (a second run is quicker  because  memory  has
already been allocated).  If  you  are  interested  in  this  sort  of
information, however, you may be better off dealing directly with  the
standalone.
When ACEStart is  called  with  no  arguments  it  finds  the  least
positive integer i for which an interactive process is  running  and
applies ACEStart(i). (Most users will  only  run  one  interactive
process at a time. Hence, ACEStart() will be a useful  shortcut  for
ACEStart(1).)
The fourth form  of  ACEStart  on  four  arguments,  invokes  a  new
enumeration on the ith running process, with new generators fgens,
relators rels and subgroup generators sgens. This is provided so a
user can re-use an already running process, rather than  start  a  new
process. This may be useful when pseudo-ttys are  a  scarce  resource.
See   the    notes    for    the    non-interactive    ACECosetTable
(ACECosetTableFromGensAndRels) which demonstrates an application  of
a usage of this and the following form of ACEStart in a loop.
The fifth form of ACEStart (on the one argument: 0)  initiates  an
interactive ACE process, processes any user options, but  does  not
insert a start (see option start) directive. This form  is  mainly
for gurus who are familiar with the ACE standalone and who wish, at
least initially,  to  communicate  with  ACE  using  the  primitive
read/write tools of  Section Primitive ACE Read/Write Functions.  In
this  case,  after  the  group  generators,  relators,  and   subgroup
generators have been set in the ACE process, invocations of any  of
ACEGroupGenerators     (see ACEGroupGenerators),     ACERelators
(see ACERelators),                           ACESubgroupGenerators
(see ACESubgroupGenerators),           or            ACEParameters
(see ACEParameters) will establish the corresponding GAP  values.
Be warned, though, that unless one of the general  ACE  modes  (see
Section General ACE modes): ACEStart (without  a  zero  argument),
ACERedo (see ACERedo) or ACEContinue (see ACEContinue), or one
of the mode options: start (see option start), redo (see option redo) or continu (see option continu), has been invoked since the
last change of any parameter options (see ACEParameterOptions), some
of the values reported by ACEParameters may well be incorrect.
The sixth form of ACEStart (on four arguments), is  like  the  first
form of ACEStart (on three  arguments),  except  that  it  does  not
insert a start  (see option  start)  directive.  It  initiates  an
interactive ACE process, with a presentation defined by its last  3
arguments.
The seventh form of ACEStart (on two arguments), is like the  second
form of ACEStart (on one argument), except that it does not insert a
start (see option start) directive. It processes any  new  options
for  the  ith  interactive  ACE  process.  ACEStart(0,  i   [:
options ] ), is similar to SetACEOptions(i  [:  options  ]  )
(see SetACEOptions), but unlike the latter does not invoke a general
mode (see Section General ACE Modes).
The last form of ACEStart (on five arguments), is  like  the  fourth
form of ACEStart (on four arguments), except that it does not insert
a start (see option  start)  directive.  It  re-uses  an  existing
interactive ACE process, with a new presentation. There is no  form
of ACEStart with the same functionality as this form, where the  i
argument is omitted.
Note:
When an interactive  ACE  process  is  initiated  by  ACEStart  a
process number i is assigned to it (the integer i returned by  the
ACEStart command), an ACE (binary) process (in the UNIX sense) is
started up, a GAP iostream is  assigned  to  communicate  with  the
ACE  (binary)  process,  and  the   essential   ``defining''   data
associated  with  the  interactive  ACE   process   is   saved   in
ACEData.io[i] (see ACEData for precisely what is saved).
ACEQuit( i ) F
ACEQuit() F
terminate an interactive ACE process,  where  i  is  the  integer
returned by ACEStart when the process was  started.  If  the  second
form is used (i.e. without arguments) then the interactive process  of
least index that is still running is terminated.
Note:
ACEQuit(i) terminates the ACE (binary) process  of  interactive
ACE process i, and closes its GAP iostream,  and  unbinds  the
record ACEData.io[i] (see ACEStart note).
It can happen that the ACE (binary) process, and hence  the  GAP
iostream assigned to communicate with it, can die,  e.g. by  the  user
typing a Ctrl-C while the ACE (binary) process is  engaged  in  a
long  calculation.  IsACEProcessAlive  (see IsACEProcessAlive)  is
provided to check the status of the GAP  iostream  (and  hence  the
status of the ACE (binary) process it was communicating  with);  in
the   case   that   it   is   indeed    dead,    ACEResurrectProcess
(see ACEResurrectProcess) may be used to start a new ACE (binary)
process and assign a new GAP iostream to communicate  with  it,  by
using the ``defining'' data of the interactive ACE process saved in
ACEData.io[i].
ACEQuitAll() F
is provided as a convenience,  to  terminate  all  active  interactive
ACE processes with a single command. It is equivalent to  executing
ACEQuit(i)  for  all  active  interactive  ACE  processes   i
(see ACEQuit).
For our purposes, we define an interactive ACE interface command to
be  an  ACE  mode,  if  it  delivers  an  enumeration  result  (see
Section Results messages). Thus, ACEStart (see ACEStart), except
when called with the  argument  0,  and  the  commands  ACERedo  and
ACEContinue which we describe below are ACE modes; we call  these
general ACE modes. Additionally, there  are  two  other  commands
which   deliver   enumeration   results:    ACEAllEquivPresentations
(see ACEAllEquivPresentations)   and   ACERandomEquivPresentations
(see ACERandomEquivPresentations); we call these ``experimentation''
ACE modes and describe them in Section Experimentation ACE Modes.
Guru Note:
The ACE standalone uses the term mode  in  a  slightly  different
sense. There, the commands: start, redo  or  continue,  put  the
ACE enumerator in start mode, redo mode or continue mode.  In
this manual, we have used the term to mean  the  command  itself,  and
generalised it  to  include  any  command  that  produces  enumeration
results.
After changing any of  ACE's  parameters,  one  of  three  general
modes is possible: one may be able to ``continue'' via  ACEContinue
(see ACEContinue), or ``redo'' via ACERedo (see ACERedo), or  if
neither of  these  is  possible  one  may  have  to  re-``start''  the
enumeration   via   ACEStart   (see ACEStart).   Generally,    the
appropriate mode is invoked automatically when options are changed; so
most users should be able to ignore the following three functions.
ACEModes( i ) F
ACEModes() F
for the ith (or default) interactive ACE process, return a record
whose fields are the modes ACEStart,  ACEContinue  and  ACERedo,
and whose values are true if the mode is possible  for  the  process
and false otherwise.
ACEContinue( i [:options] ) F
ACEContinue( [:options] ) F
for the ith (or  default)  interactive  ACE  process,  apply  any
options and then ``continue'' the current enumeration, building upon
the existing table. If a previous  run  stopped  without  producing  a
finite index you can, in principle, change  any  of  the  options  and
continue on. Of course, if you make any changes which  invalidate  the
current table, you won't be allowed to ACEContinue and an error will
be raised. However, after quitting the break-loop, the interactive
ACE process should normally still be active; after  doing  so,  run
ACEModes (see ACEModes) to see which of ACERedo or ACEStart is
possible.
ACERedo( i [:options] ) F
ACERedo( [:options] ) F
for the ith (or default) interactive ACE process, apply any options and then ``redo'' the current enumeration from coset 1 (i.e., the subgroup), keeping any existing information in the table.
Notes:
The  difference  between  ACEContinue  and  ACERedo  is   somewhat
technical, and the user should regard it as a mode that  is  a  little
more  expensive  than  ACEContinue  but  cheaper  than   ACEStart.
ACERedo is really intended for the case  where  additional  relators
and/or subgroup generators have been introduced;  the  current  table,
which may be incomplete or exhibit a finite index, is still ``valid''.
However, the new data may allow the enumeration to complete, or  cause
a collapse to a smaller index. In some cases,  ACERedo  may  not  be
possible and an error  will  be  raised;  in  this  case,  quit  the
break-loop, and try ACEStart, which will discard the current table
and re-``start'' the enumeration.
ACEProcessIndex( i ) F
ACEProcessIndex() F
With argument i, which must be a positive integer, ACEProcessIndex
returns i if it corresponds to an  active  interactive  process,  or
raises an error. With no  arguments  it  returns  the  default  active
interactive process or returns fail and emits a warning  message  to
Info at InfoACE or InfoWarning level 1.
Note:
Essentially, an  interactive  ACE  process  i  is  ``active''  if
ACEData.io[i] is bound (i.e. we still have some  data  telling  us
about it). Also see ACEStart note.
ACEProcessIndices() F
returns the list of integer indices of all active interactive ACE processes (see ACEProcessIndex for the meaning of ``active'').
IsACEProcessAlive( i ) F
IsACEProcessAlive() F
return true if  the  GAP  iostream  of  the  ith  (or  default)
interactive ACE process started by ACEStart  is  alive  (i.e. can
still  be  written  to),  or  false,  otherwise.  (See   the   notes
for ACEStart and ACEQuit.)
If the user does not yet have a gap> prompt then usually  ACE  is
still away doing something and an ACE interface function  is  still
waiting for a reply from ACE. Typing a Ctrl-C (i.e. holding  down
the Ctrl key and typing c) will stop the waiting and  send  GAP
into a break-loop, from which one has no option but to quit;.  The
typing of Ctrl-C, in such a circumstance, usually causes the  stream
of the interactive ACE process to die; to  check  this  we  provide
IsACEProcessAlive (see IsACEProcessAlive). If  the  stream  of  an
interactive ACE process, indexed by i,  say,  has  died,  it  may
still be possible to recover enough of the state, before the death  of
the stream, from  the  information  stored  in  the  ACEData.io[i]
record (see Section The ACEData Record). For such a purpose, we have
provided ACEResurrectProcess (see ACEResurrectProcess).
The GAP iostream of an interactive ACE process will also die  if
the ACE binary has a segmentation fault. We do hope that this never
happens to you, but if it does and the failure is  reproducible,  then
it's a bug and we'd like to know about it. Please  read  the  README
that comes with the ACE package to find out what to  include  in  a
bug report and who to email it to.
ACEResurrectProcess( i [: options] ) F
ACEResurrectProcess( [: options] ) F
re-generate the GAP iostream of the ith (or default)  interactive
ACE process started by ACEStart (see ACEStart, the final  note,
in particular), and try to recover as much as possible of the previous
state from saved values  of  the  process's  arguments  and  parameter
options. The possible options here are use and useboth which are
described in detail below.
The arguments of the ith interactive ACE process  are  stored  in
ACEData.io[i].args, a  record  with  fields  fgens,  rels  and
sgens, which are the GAP group generators, relators and  subgroup
generators, respectively (see Section The  ACEData  Record).  Option
information is saved in ACEData.io[i].options when a user uses  an
interactive  ACE  interface   function   with   options   or   uses
SetACEOptions (see SetACEOptions). Parameter option information is
saved in ACEData.io[i].parameters if ACEParameters (see ACEParameters)
is used to extract from  ACE  the  current  values  of  the  ACE
parameter options (this is generally less reliable unless one  of  the
general ACE modes (see Section General ACE Modes), has  been  run
previously).
By   default,   ACEResurrectProcess   recovers   parameter    option
information from ACEData.io[i].options if it  is  bound,  or  from
ACEData.io[i].parameters  if   it   is   bound,   otherwise.   The
ACEData.io[i].options  record,  however,  is  first  filtered  for
parameter and  strategy  options  (see  Sections ACEParameterOptions
and The ACEStrategyOptions list) and the echo option  (see option echo). To alter this behaviour, the user is provided two options:
use := useList"options"  and  "parameters".  By  default,  use  =   ["options",
"parameters"].
useboth useboth = false.
If useboth = true, SetACEOptions (see SetACEOptions) is  applied
to    the    ith    interactive    ACE    process    with    each
ACEData.io[i].(field)   for   each   field   ("options"   or
"parameters") that is bound and in useList, in the  order  implied
by useList. If useboth = false, SetACEOptions  is  applied  with
ACEData.io[i].(field) for only the first field that  is  bound
in useList. The current value of the echo option is also preserved
(no matter what values the user chooses for the  use  and  useboth
options).
Notes:
Do not use general ACE  options  with  ACEResurrectProcess;  they
will  only   be   superseded   by   those   options   recovered   from
ACEData.io[i].options     and/or     ACEData.io[i].parameters.
Instead, call SetACEOptions first (or afterwards). When called prior
to ACEResurrectProcess, SetACEOptions will emit a warning that the
stream is dead; despite this, the ACEData.io[i].options will  be
updated.
ACEResurrectProcess  does  not  invoke   an   ACE   mode   (see
Section General ACE  Modes).  This  leaves  the  user  free  to  use
SetACEOptions (which does invoke an ACE mode) to  further  modify
options afterwards.
ToACEGroupGenerators( fgens ) F
This function produces, from a  GAP  list  fgens  of  free  group
generators, the  ACE  directive  string  required  by  the  group
(see option group) option. (The group option may be used to define
the equivalent of fgens in an ACE process.)
ToACEWords( fgens, words ) F
This function produces, from a  GAP  list  words  in  free  group
generators fgens, a string  that  represents  those  words  as  an
ACE list of words. ToACEWords may be  used  to  provide  suitable
values   for   the   options   relators   (see option   relators),
generators (see option generators), sg  (see option  sg),  and
rl (see option rl).
Now we describe the two experimentation modes. The term mode was defined in Section General ACE Modes.
ACEAllEquivPresentations( i, val ) F
ACEAllEquivPresentations( val ) F
for the ith (or default) interactive ACE process, generates and tests an enumeration for combinations of relator ordering, relator rotations, and relator inversions; val is in the integer range 1 to 7.
The argument val is considered as a binary number. Its three bits are treated as flags, and control relator rotations (the 20 bit), relator inversions (the 21 bit) and relator orderings (the 22 bit), respectively; where 1 means ``active'' and 0 means ``inactive''. (See below for an example).
Before we describe the GAP output of ACEAllEquivPresentations let
us spend some time considering what happens before the  ACE  binary
output is parsed.
The ACEAllEquivPresentations  command  first  performs  a  ``priming
run'' using the options as they stand. In particular, the  asis  and
messages options are honoured.
It  then  turns  asis  (see option   asis)   on   and   messages
(see option messages) off (i.e. sets messages to 0), and generates
and tests the requested  equivalent  presentations.  The  maximum  and
minimum values attained by m (the maximum number  of  coset  numbers
defined at any stage) and t  (the  total  number  of  coset  numbers
defined) are tracked, and each time the  statistics  are  better  than
what we've already seen, the ACE binary emits a summary result line
for the relators used. See  Appendix The  Meanings  of  ACE's  output messages for a discussion of the statistics m and t.  To  observe
these messages set  the  InfoLevel  of  InfoACE  to  3;  and  it's
recommended that you do this so that you get some idea of  what  the
ACE binary is doing.
The order in which the  equivalent  presentations  are  generated  and
tested has no particular significance, but note that the  presentation
as given after the initial priming run) is the  last  presentation
to be generated and tested, so that  the  group's  relators  are  left
``unchanged'' by running the ACEAllEquivPresentations command.
As discussed by Cannon, Dimino, Havas and Watson CDHW73 and Havas and Ramsay HR01 such equivalent presentations can yield large variations in the number of coset numbers required in an enumeration. For this command, we are interested in this variation.
After the final presentation is run, some additional status information messages are printed to the ACE output:
m and t.
As an example (drawn from the discussion in HR99ace) consider the
enumeration   of   the   448   coset   numbers   of   the   subgroup
áa2,a-1b ñ of the group
| 
 | 
Now we describe the output  of  ACEAllEquivPresentations;  it  is  a
record with fields:
primingResult 
primingStats index,   cputime,   cputimeUnits,
activecosets, maxcosets and totcosets, exactly as for the record
returned by ACEStats (see ACEStats);
equivRuns 
rels
enumResult
statsACEStats (see ACEStats);
summary 
successes
runs
maxcosetsRangeequivRuns[i].maxcosets lies, and
totcosetsRangeequivRuns[i].totcosets lies.
Notes:
In general, the length of the equivRuns field list will be less than
the number of runs executed.
There is no way to stop the ACEAllEquivPresentations command  before
it has completed, other than killing the task. So do a  reality  check
beforehand on the size of the search  space  and  the  time  for  each
enumeration. If you are interested in finding a ``good''  enumeration,
it can be very helpful, in terms of running time, to put a tight limit
on the number of coset numbers via the max option. You may also have
to set compaction  =  100  to  prevent  time-wasting  attempts  to
recover space via compaction. This maximises throughput by causing the
``bad'' enumerations, which are in the majority, to  overflow  quickly
and abort. If you wish to explore a very large search-space,  consider
firing up many copies of ACE, and starting each with  a  ``random''
equivalent   presentation.   Alternatively,   you   could   use    the
ACERandomEquivPresentations command.
ACERandomEquivPresentations( i, val ) F
ACERandomEquivPresentations( val ) F
ACERandomEquivPresentations( i, [val] ) F
ACERandomEquivPresentations( [val] ) F
ACERandomEquivPresentations( i, [val, Npresentations] ) F
ACERandomEquivPresentations( [val, Npresentations] ) F
for the ith (or default) interactive ACE process,  generates  and
tests up to Npresentations (or 8,  in  the  first  4  forms)  random
presentations; val, an integer in the range 1  to  7,  acts  as  for
ACEAllEquivPresentations and Npresentations, when given, should be
a positive integer.
The routine first turns asis (see option asis) on  and  messages
(see option messages) off (i.e. sets  messages  to  0),  and  then
generates  and  tests  the  requested  number  of  random   equivalent
presentations. For  each  presentation,  the  relators  used  and  the
summary result line are printed by ACE. To observe  these  messages
set the InfoLevel of InfoACE to at least 3.
ACERandomEquivPresentations parses the ACE messages,  translating
them to GAP, and thus returns a list of  records  (similar  to  the
field     equivRuns     of     the      returned      record      of
ACEAllEquivPresentations). Each record of the returned list  is  the
data derived from a presentation run and has fields:
rels
enumResult
statsACEStats (see ACEStats).
Notes:
The relator inversions and rotations  are  ``genuinely''  random.  The
relator permuting is a little bit of a kludge, with the ``quality'' of
the permutations tending to  improve  with  successive  presentations.
When  the   ACERandomEquivPresentations   command   completes,   the
presentation active is the last one generated.
Guru Notes:
It might appear that neglecting to restore the  original  presentation
is an error. In fact, it is a useful feature! Suppose that  the  space
of equivalent presentations is too  large  to  exhaustively  test.  As
noted in the entry for ACEAllEquivPresentations,  we  can  start  up
multiple copies of ACEAllEquivPresentations at random points in  the
search-space. Manually generating random equivalent presentations to
serve   as   starting-points   is   tedious   and   error-prone.   The
ACERandomEquivPresentations  command  provides  a  simple  solution;
simply    run    ACERandomEquivPresentations(i,     7);     before
ACEAllEquivPresentations(i, 7);.
ACEGroupGenerators( i ) F
ACEGroupGenerators() F
return  the  GAP  group  generators  of  the  ith  (or   default)
interactive ACE process. If no generators have been saved  for  the
interactive ACE process, possibly because the process  was  started
via   ACEStart(0);   (see ACEStart),   the   ACE   process   is
interrogated, and the equivalent in  GAP  is  saved  and  returned.
Essentially,   ACEGroupGenerators(i)   interrogates   ACE   and
establishes ACEData.io[i].args.fgens, if  necessary,  and  returns
ACEData.io[i].args.fgens.  As  a  side-effect,  if  any   of   the
remaining       fields       of       ACEData.io[i].args        or
ACEData.io[i].acegens are unset, they  are  also  set.  Note  that
GAP provides  GroupWithGenerators  (see GroupWithGenerators
in the GAP Reference Manual) to establish a free group on  a  given
set of already-defined generators.
ACERelators( i ) F
ACERelators() F
return the GAP relators  of  the  ith  (or  default)  interactive
ACE process. If no relators have been  saved  for  the  interactive
ACE  process,  possibly  because  the  process  was   started   via
ACEStart(0); (see ACEStart), the ACE process  is  interrogated,
the  equivalent  in  GAP  is  saved  and   returned.   Essentially,
ACERelators(i)     interrogates     ACE     and     establishes
ACEData.io[i].args.rels,     if     necessary,     and     returns
ACEData.io[i].args.rels. As a side-effect, if any of the remaining
fields  of  ACEData.io[i].args  or  ACEData.io[i].acegens  are
unset, they are also set.
ACESubgroupGenerators( i ) F
ACESubgroupGenerators() F
return the GAP  subgroup  generators  of  the  ith  (or  default)
interactive ACE process. If no subgroup generators have been  saved
for the interactive ACE process, possibly because the  process  was
started via ACEStart(0); (see ACEStart),  the  ACE  process  is
interrogated,  the  equivalent  in  GAP  is  saved  and   returned.
Essentially,  ACESubgroupGenerators(i)  interrogates  ACE   and
establishes ACEData.io[i].args.sgens, if  necessary,  and  returns
ACEData.io[i].args.sgens.  As  a  side-effect,  if  any   of   the
remaining       fields       of       ACEData.io[i].args        or
ACEData.io[i].acegens are unset, they are also set.
DisplayACEArgs( i ) F
DisplayACEArgs() F
display the arguments (i.e. fgens, rels and sgens) of the  ith
(or   default)   process   started    by    ACEStart.    In    fact,
DisplayACEArgs(i)   is    just    a    pretty-printer    of    the
ACEData.io[i].args record. Use GetACEArgs  (see GetACEOptions)
in          assignments.          Unlike          ACEGroupGenerators
(see ACEGroupGenerators),  ACERelators   (see ACERelators)   and
ACESubgroupGenerators                 (see ACESubgroupGenerators),
DisplayACEArgs does not have the side-effect of setting any  of  the
fields of ACEData.io[i].args if they are unset.
GetACEArgs( i ) F
GetACEArgs() F
return a record of the current  arguments  (i.e. fgens,  rels  and
sgens) of the ith (or default) process started by  ACEStart.  In
fact, GetACEOptions(i) simply returns  the  ACEData.io[i].args
record,  or  an  empty  record  if  that  record  is  unbound.  Unlike
ACEGroupGenerators     (see ACEGroupGenerators),     ACERelators
(see ACERelators)            and             ACESubgroupGenerators
(see ACESubgroupGenerators),  GetACEOptions  does  not  have   the
side-effect of setting any of the fields of ACEData.io[i].args  if
they are unset.
DisplayACEOptions( i ) F
DisplayACEOptions() F
display the options, explicitly set by the user, of the  ith  (or  default)  process  started  by
ACEStart. In fact, DisplayACEOptions(i) is just a pretty-printer
of   the   ACEData.io[i].options   record.   Use   GetACEOptions
(see GetACEOptions) in assignments. Please note that no-value ACE
options  will   appear   with   the   assigned   value   true   (see
Section Interpretation of ACE Options for how the  ACE  interface
functions interpret such options). 
Notes: 
Any  options  set  via  ACEWrite  (see ACEWrite)  will  not   be
displayed. Also, recall that if ACE is not  given  any  options  it
uses the default strategy  (see  Section What  happens  if  no  ACE Strategy Option or if no ACE  Option  is  passed).  To  discover  the
various    settings    of     the     ACE     Parameter     Options
(see ACEParameterOptions) in  vogue  for  the  ACE  process,  use
ACEParameters (see ACEParameters).
GetACEOptions( i ) F
GetACEOptions() F
return  a  record  of  the  current  options  (those  that  have  been
explicitly set by the user) of the ith (or default) process  started
by ACEStart. Please note that no-value ACE  options  will  appear
with the assigned value true  (see  Section Interpretation  of  ACE Options  for  how  the  ACE  interface  functions  interpret  such
options).    The     notes     applying     to     DisplayACEOptions
(see DisplayACEOptions) also apply here.
SetACEOptions( i [:options] ) F
SetACEOptions( [:options] ) F
modify the current options of the ith (or default)  process  started
by ACEStart. Please ensure that the OptionsStack is  empty  before
calling SetACEOptions, otherwise the options already present on  the
OptionsStack will also be ``seen''. All interactive ACE interface
functions that accept options, actually call an  internal  version  of
SetACEOptions;  so,  it  is  generally   important   to   keep   the
OptionsStack clear while working with ACE interactively.
After setting the options passed, the first  mode  of  the  following:
ACEContinue  (see ACEContinue),   ACERedo   (see ACERedo)   or
ACEStart (see ACEStart), that may  be  applied,  is  automatically
invoked.
Since  a  user  will   sometimes have options in the form  of a record 
(e.g. via GetACEOptions),   we    provide  an  alternative  to   the
behind-the-colon  syntax,  in a  manner .like  PushOptions, for  the
passing of options via SetACEOptions:
SetACEOptions( i, optionsRec ) F
SetACEOptions( optionsRec ) F
In this form, the record optionsRec is used to  update  the  current
options of the ith (or default) process started by ACEStart.  Note
that since optionsRec is a record each field must have  an  assigned
value; in particular, no-value ACE options should be  assigned  the
value true (see Section Interpretation  of  ACE  Options).  Please
don't mix these two forms of SetACEOptions  with  the  previous  two
forms; i.e. do not pass both a record argument  and  options,  since
this will lead to options appearing in the wrong order; if you want to
do this, make two separate calls to  SetACEOptions,  e.g. let's  say
you have a process like that started by:
gap> ACEExample("A5", ACEStart);
then the following demonstrates both usages of SetACEOptions:
gap> SetACEOptions( rec(echo := 2) ); gap> SetACEOptions( : hlt);
Each of the three commands above generates output; for brevity it has not been included.
Notes:
When    ACECosetTableFromGensAndRels    enters    a     break-loop
(see ACECosetTable), local versions of the second form  of  each  of
DisplayACEOptions and SetACEOptions become available. (Even though
the names are similar and their function is analogous they are in fact
different functions.)
ACEParameters( i ) F
ACEParameters() F
return a record of the current values of the ACE Parameter  Options
(see ACEParameterOptions) of the ith (or default) process  started
by ACEStart, according to ACE. Please note that some options  may
be reported with incorrect values if they have been  changed  recently
without following up with one of the modes ACEContinue, ACERedo or
ACEStart. Together the commands ACEGroupGenerators, ACERelators,
ACESubgroupGenerators and ACEParameters give the equivalent GAP
information that is obtained in ACE with  sr  :=  1  (see option sr), which is the ``Run Parameters'' block obtained in the  messaging
output (observable when the InfoLevel of  InfoACE  is  set  to  at
least 3), when messages (see option messages) is  set  a  non-zero
value.
Notes:
One use for this function might be to determine the  options  required
to replicate a previous run,  but  be  sure  that,  if  this  is  your
purpose, any recent change in the parameter  option  values  has  been
followed by an invocation of one of ACEContinue (see ACEContinue),
ACERedo (see ACERedo) or ACEStart (see ACEStart).
As a side-effect, for  ACE  process  i,  any  of  the  fields  of
ACEData.io[i].args or ACEData.io[i].acegens  that  are  unset,
are set.
IsCompleteACECosetTable( i ) F
IsCompleteACECosetTable() F
return, for the ith (or  default)  process  started  by  ACEStart,
true if  ACE's  current  coset  table  is  complete,  or  false
otherwise.
Note:
The completeness of the coset table of the  ith  interactive  ACE
process      is       determined       by       checking       whether
ACEData.io[i].stats.index is positive; a value of  zero  indicates
the   last   enumeration    failed    to    complete.    The    record
ACEData.io[i].stats  is  what  is  returned   by   ACEStats(i)
(see ACEStats).
ACEDisplayCosetTable( i ) F
ACEDisplayCosetTable() F
ACEDisplayCosetTable( i, [val] ) F
ACEDisplayCosetTable( [val] ) F
ACEDisplayCosetTable( i, [val, last] ) F
ACEDisplayCosetTable( [val, last] ) F
ACEDisplayCosetTable( i, [val, last, by] ) F
ACEDisplayCosetTable( [val, last, by] ) F
compact and display the (possibly incomplete) coset table of the ith
(or default) process started by ACEStart; val must be an  integer,
and last and by must be positive integers. In the first two  forms
of the command, the entire coset table is displayed, without orders or
coset representatives. In the third and  fourth  forms,  the  absolute
value of val is taken to be  the  last  line  of  the  table  to  be
displayed (and 1 is taken to be the first); in  the  fifth  and  sixth
forms, |val| is taken to be the first line  of  the  table  to  be
displayed, and last is taken to be the number of the last line to be
displayed. In the last two forms, the table  is  displayed  from  line
|val| to line last in steps of by. If val is negative,  then
the  orders   modulo   the   subgroup   (if   available)   and   coset
representatives are displayed also.
Note:
The coset table displayed will normally only be lenlex  standardised
if   the   call   to    ACEDisplayCosetTable    is    preceded    by
ACEStandardCosetNumbering   (see ACEStandardCosetNumbering).   The
options lenlex (see option lenlex) and  semilenlex  (see option semilenlex)     are     only     executed     by      ACECosetTable
(see ACECosetTable). The ACE binary does not provide semilenlex
standardisation, and hence ACEDisplayCosetTable will never display a
semilenlex standard coset table.
ACECosetRepresentative( i, n ) F
ACECosetRepresentative( n ) F
return, for the ith (or default) process started by ACEStart,  the
coset representative of coset n of the current coset table  held  by
ACE, where n must be a positive integer.
ACECosetRepresentatives( i ) F
ACECosetRepresentatives() F
return, for the ith (or default) process started by ACEStart,  the
list of coset representatives of  the  current  coset  table  held  by
ACE.
ACETransversal( i ) F
ACETransversal() F
return, for the ith (or default) process started by ACEStart,  the
list of coset representatives of  the  current  coset  table  held  by
ACE, if the  current  table  is  complete,  and  fail  otherwise.
Essentially, ACETransversal(i) = ACECosetRepresentatives(i)  for
a complete table.
ACECycles( i ) F
ACECycles() F
ACEPermutationRepresentation( i ) F
ACEPermutationRepresentation() F
return, for the ith (or default) process started  by  ACEStart,  a
list of permutations corresponding to the group generators, (i.e., the
permutation representation), if the current coset table held by ACE
is complete or fail, otherwise. In the event of failure a message is
emitted to Info at InfoACE or InfoWarning level 1.
ACETraceWord( i, n, word ) F
ACETraceWord( n, word ) F
for the ith (or  default)  interactive  ACE  process  started  by
ACEStart, trace word through ACE's  coset  table,  starting  at
coset n, and return the final coset number if the  trace  completes,
and fail otherwise. In Group  Theory  terms,  if  the  cosets  of  a
subgroup H in a group G are  the  subject  of  interactive  ACE
process i and the coset identified by that process  by  the  integer
n corresponds to some coset Hx, for some x in  G,  and  word
represents the element g of G, then, providing the  current  coset
table is complete enough, ACETraceWord( i, n, word  )  returns
the integer identifying the coset Hxg.
Notes:
You may wish to compact ACE's coset table first, either  explicitly
via ACERecover (see ACERecover), or, implicitly, via any  function
call that invokes ACE's compaction routine (see ACERecover note).
If you actually wanted ACE's  coset  representative,  then,  for  a
compact   table,   feed   the   output    of    ACETraceWord    to
ACECosetRepresentative (see ACECosetRepresentative).
ACEOrders( i ) F
ACEOrders() F
ACEOrders( i : suborder := suborder ) F
ACEOrders(: suborder := suborder ) F
for the ith (or  default)  interactive  ACE  process  started  by
ACEStart, search for all coset numbers whose representatives' orders
(modulo the subgroup) are either  finite,  or,  if  invoked  with  the
suborder option,  are  multiples  of  suborder,  where  suborder
should be a positive integer. ACEOrders returns a  (possibly  empty)
list of records, each with fields coset, order  and  rep,  which
are respectively, the coset number, its order modulo the subgroup, and
a representative for each coset number satisfying the criteria of  the
search.
Note:
You may wish to compact ACE's coset table first, either  explicitly
via ACERecover (see ACERecover), or, implicitly, via any  function
call that invokes ACE's compaction routine (see ACERecover note).
ACEOrder( i, suborder ) F
ACEOrder( suborder ) F
for the ith (or  default)  interactive  ACE  process  started  by
ACEStart, search for coset  number(s)  whose  coset  representatives
have  order  modulo  the  subgroup  a  multiple  of  suborder.  When
suborder is a positive integer, ACEOrder returns just  one  record
with fields coset, order and rep, which  are  respectively,  the
coset number, its order modulo the subgroup, and a representative  for
the first coset number satisfying  the  criteria  of  the  search,  or
fail if there is no such coset number. The value of  suborder  may
also be a negative integer, in which case, ACEOrder( i,  suborder
) is equivalent to ACEOrders( i : suborder :=  |suborder|);  or
suborder may be zero,  in  which  case,  ACEOrder(  i,  0  )  is
equivalent to ACEOrders( i ).
Note:
You may wish to compact ACE's coset table first, either  explicitly
via ACERecover (see ACERecover), or, implicitly, via any  function
call that invokes ACE's compaction routine (see ACERecover note).
ACECosetOrderFromRepresentative( i, cosetrep ) F
ACECosetOrderFromRepresentative( cosetrep ) F
for the ith (or default) interactive ACE process return the order (modulo the subgroup) of the coset with representative cosetrep, a word in the free group generators.
Note:   
ACECosetOrderFromRepresentative calls  ACETraceWord  to  determine
the coset (number) to which cosetrep belongs,  and  then  scans  the
output of ACEOrders to determine the order of the coset (number).
ACECosetsThatNormaliseSubgroup( i, n ) F
ACECosetsThatNormaliseSubgroup( n ) F
for the ith (or  default)  interactive  ACE  process  started  by
ACEStart, determine non-trivial  (i.e. other  than  coset  1)  coset
numbers whose representatives normalise the subgroup.
coset  and
rep  which  represent  the  coset  number  and   a   representative,
respectively,  of  the  first  n  non-trivial  coset  numbers  whose
representatives normalise the subgroup is returned.
coset  and
rep  which  represent  the  coset  number  and   a   representative,
respectively, of all non-trivial coset numbers  whose  representatives
normalise the subgroup is returned.
Note:
You may wish to compact ACE's coset table first, either  explicitly
via ACERecover (see ACERecover), or, implicitly, via any  function
call that invokes ACE's compaction routine (see ACERecover note).
ACEStyle( i ) F
ACEStyle() F
returns the current enumeration style as one of  the  strings:  "C",
"Cr", "CR", "R", "R*", "Rc", "R/C", or "R/C (defaulted)"
(see Section Enumeration Style).
The next two functions of this section are really intended for ACE standalone gurus. To fully understand their output you will need to consult the standalone manual and the C source code.
ACEDumpVariables( i ) F
ACEDumpVariables() F
ACEDumpVariables( i, [level] ) F
ACEDumpVariables( [level] ) F
ACEDumpVariables( i, [level, detail] ) F
ACEDumpVariables( [level, detail] ) F
dump the internal variables  of  ACE  of  the  ith  (or  default)
process started by ACEStart; level should be one of 0,  1,  or  2,
and detail should be 0 or 1.
The value of level determines which of the three levels of ACE to
dump. (You will need to read the standalone manual to understand  what
Levels 0, 1 and 2 are all about.) The value of detail determines the
amount of detail (detail = 0 means less  detail).  The  first  two
forms of ACEDumpVariables (with no list argument) selects level =
0, detail = 0. The third and fourth forms  (with  a  list  argument
containing the integer level) makes detail = 0. This command  is
intended for gurus; the source code should be consulted  to  see  what
the output means.
ACEDumpStatistics( i ) F
ACEDumpStatistics() F
dump ACE's internal statistics accumulated during the  most  recent
enumeration of the ith (or default) process started  by  ACEStart,
provided the ACE binary  was  built  with  the  statistics  package
(which    it    is    by    default).    Use     ACEBinaryVersion();
(see ACEBinaryVersion) to check for the inclusion of the  statistics
package.  See  the  enum.c  source  file  for  the  meaning  of  the
variables.
ACEBinaryVersion( i ) F
ACEBinaryVersion() F
for the ith (or default) process started by ACEStart,  print,  via
Info (at InfoACE level 1), version details of  the  ACE  binary
you are currently running, including what compiler flags were set when
the executable was built, and also returns the version number  of  the
binary as a string. Essentially the information obtained  is  what  is
obtained via ACE's options option (see option options), and the
returned value is what is stored in ACEData.version (see ACEData).
A typical output, illustrating the default build, is:
gap> ACEBinaryVersion(); #I No interactive ACE sessions are currently active #I ACE Binary Version: 3.001 #I ACE 3.001 Sat Feb 27 11:27:15 2016 #I ========================================= #I Host information: #I name = banksia #I ACE 3.001 executable built: #I Wed Feb 24 15:25:26 AWST 2016 #I Level 0 options: #I statistics package = on #I coinc processing messages = on #I dedn processing messages = on #I Level 1 options: #I workspace multipliers = decimal #I Level 2 options: #I host info = on "3.001"
Notes:
The ACE binary's banner may also appear in the output  (if  it  has
not already appeared). Unlike other ACE  interface  functions,  the
information   obtained   via   ACEBinaryVersion();   is   absolutely
independent  of  any  enumeration.  For  this  reason,  we   make   it
permissible to run ACEBinaryVersion(); when there are  no  currently
active  interactive  ACE  processes;   and,   in   such   a   case,
ACEBinaryVersion(); emits a warning that there  are  no  interactive
ACE sessions currently active and initiates (and closes again)  its
own stream to obtain the information from the ACE binary.  For  the
current version of the ACE package (the GAP code component)  use
ACEPackageVersion(); (see ACEPackageVersion).
ACECosetTable( i [:options] ) F
ACECosetTable( [:options] ) F
return a coset table  as  a  GAP  object,  in  standard  form  (for
GAP).   These   functions   perform   the    same    function    as
ACECosetTableFromGensAndRels and ACECosetTable on three  arguments
(see ACECosetTable), albeit interactively, on the ith (or default)
process started by ACEStart. If options are passed then an  internal
version of ACEModes is run to determine which of the general  ACE
modes (see Section General ACE Modes)  ACEContinue,  ACERedo  or
ACEStart is possible; and (an internal version of) the first mode of
these that is allowed is executed, to ensure the  resultant  table  is
correct for the current options.
ACEStats( i [:options] ) F
ACEStats( [:options] ) F
perform  the  same  function  as   ACEStats   on   three   arguments
(see ACEStats --- non-interactive version), albeit interactively, on
the ith (or default) process started by ACEStart. If  options  are
passed then an internal version of  ACEModes  is  run  to  determine
which of the general ACE modes (see  Section General  ACE  Modes)
ACEContinue, ACERedo or ACEStart is possible; and  (an  internal
version of) the first mode of these that is allowed  is  executed,  to
ensure the resultant statistics are correct for the current options.
See Section Example of Using ACE Interactively (Using ACEStart) for an example demonstrating both these functions within an interactive process.
IsACEGeneratorsInPreferredOrder( i ) F
IsACEGeneratorsInPreferredOrder() F
for the ith (or  default)  interactive  ACE  process  started  by
ACEStart, return true if the group generators of that process, are
in an order that will not be changed by ACE, and false otherwise.
This function has greatest relevance to users who call ACECosetTable
(see ACECosetTable!interactive),   with    the    lenlex    option
(see option lenlex). For more details, see the  discussion  for  the
non-interactive    version    of     IsACEGeneratorsInPreferredOrder
(IsACEGeneratorsInPreferredOrder),  which   is   called   with   two
arguments.
ACERecover( i ) F
ACERecover() F
invoke the compaction routine on the coset  table  of  the  ith  (or
default) interactive ACE process started by ACEStart, in order to
recover the space used by the dead coset numbers. A CO message  line
is printed if any rows of the coset table were recovered, and  a  co
line if  none  were.  (See  Appendix The  Meanings  of  ACE's  output messages for the meanings of these messages.)
Note:
The  compaction  routine  is  called   automatically   when   any   of
ACEDisplayCosetTable                   (see ACEDisplayCosetTable),
ACECosetRepresentative               (see ACECosetRepresentative),
ACECosetRepresentatives             (see ACECosetRepresentatives),
ACETransversal          (see ACETransversal),          ACECycles
(see ACECycles),                         ACEStandardCosetNumbering
(see ACEStandardCosetNumbering),                     ACECosetTable
(see ACECosetTable)    or    ACEConjugatesForSubgroupNormalClosure
(see ACEConjugatesForSubgroupNormalClosure), is invoked.
ACEStandardCosetNumbering( i ) F
ACEStandardCosetNumbering() F
compact and then do a  lenlex  standardisation  (see  Section Coset Table Standardisation Schemes) of the  numbering  of  cosets  in  the
coset table of the  ith  (or  default)  interactive  ACE  process
started by ACEStart. That is, for a given ordering of the generators
in the columns of the table, they produce a  canonic  table.  A  table
that  includes  a  column  for  each  generator  inverse   immediately
following the column for  the  corresponding  generator,  standardised
according to the lenlex scheme, has the property  that  a  row-major
scan (i.e. a scan of the successive rows of the body  of  the  table
row by row, from left to right) encounters previously unseen cosets in
numeric order. This function does  not  display  the  new  table;  use
ACEDisplayCosetTable (see ACEDisplayCosetTable) for that.
Notes:
In a lenlex canonic table, the  coset  representatives  are  ordered
first according to length and then the lexicographic order defined  by
the order the generators and their inverses  head  the  columns.  Note
that,  unless  special  action  is  taken,  ACE  avoids  having  an
involutory generator in the first column (by swapping  the  first  two
generators), except when there is only  one  generator,  or  when  the
second generator is also an involution;  so  the  lexicographic  order
used by ACE need not necessarily correspond with the order in which
the generators were first put  to  ACE.  (We  have  used  the  term
``involution'' above; what we really mean is  a  generator  x  for
which there is a relator x*x or x^2.  Such  a  generator  may,  of
course,  turn  out  to  actually  be  the  identity.)   The   function
IsACEGeneratorsInPreferredOrder                                 (see
IsACEGeneratorsInPreferredOrder) detects  cases  when  ACE  would
swap the first two generators.
Standardising the coset numbering within ACE does not affect  the
GAP coset table obtained via ACECosetTable (see ACECosetTable).
If ACECosetTable is called  without  the  lenlex  option  GAP's
default  standardisation  is  applied  after  conversion  of  ACE's
output, which undoes an ACE standardisation. On the other hand,  if
ACECosetTable is called with the lenlex option then after a  check
and  special  action,  if  required,  the  equivalent  of  a  call  to
ACEStandardCosetNumbering is invoked, irrespective of whether it has
been done by the user beforehand. The check that is done is a call  to
IsACEGeneratorsInPreferredOrder                                 (see
IsACEGeneratorsInPreferredOrder)  to  ensure  that  ACE  has  not
swapped the first two generators. The special action  taken  when  the
call to  IsACEGeneratorsInPreferredOrder  returns  false,  is  the
setting of  the  asis  option  (see option  asis)  to  1  and  the
resubmission of the relators to ACE taking care not to  submit  the
relator that determines the first generator as an involution  as  that
generator squared (these two actions together avert ACE's  swapping
of the first two generators), followed by  the  re-starting  of  the
enumeration.
Guru Notes: In five of the ten standard enumeration strategies of Sims Sim94 (i.e. the five Sims strategies not provided by ACE), the table is standardised repeatedly. This is expensive computationally, but can result in fewer cosets being necessary. The effect of doing this can be investigated in ACE by (repeatedly) halting the enumeration (via restrictive options), standardising the coset numbering, and continuing (see Section Emulating Sims for an example).
ACEAddRelators( i, wordlist ) F
ACEAddRelators( wordlist ) F
add, for the ith (or default) interactive ACE process started  by
ACEStart, the words in the list wordlist to any  relators  already
present, and automatically invoke ACERedo, if it can be applied,  or
otherwise ACEStart. Note that ACE  sorts  the  resultant  relator
list, unless the asis option (see option asis) has been set to  1;
don't assume, unless asis = 1,  that  the  new  relators  have  been
appended in user-provided order to  the  previously  existing  relator
list.  ACEAddRelators  also  returns  the  new  relator  list.   Use
ACERelators (see ACERelators) to  determine  the  current  relator
list.
ACEAddSubgroupGenerators( i, wordlist ) F
ACEAddSubgroupGenerators( wordlist ) F
add, for the ith (or default) interactive ACE process started  by
ACEStart,  the  words  in  the  list  wordlist  to  any   subgroup
generators already present, and automatically invoke ACERedo, if  it
can be applied, or otherwise ACEStart. Note that  ACE  sorts  the
resultant  subgroup  generator  list,   unless   the   asis   option
(see option asis) has been set to 1; don't assume,  unless  asis  =
1,  that  the  new  subgroup  generators  have   been   appended   in
user-provided order to  the  previously  existing  subgroup  generator
list.  ACEAddSubgroupGenerators  also  returns  the   new   subgroup
generator          list.          Use          ACESubgroupGenerators
(see ACESubgroupGenerators)  to  determine  the   current   subgroup
generator list.
ACEDeleteRelators( i, list ) F
ACEDeleteRelators( list ) F
for the ith (or  default)  interactive  ACE  process  started  by
ACEStart, delete list from the current relators, if list is a list
of words in the group generators, or those current relators indexed by
the integers in list, if list is a list of positive integers,  and
automatically invoke ACEStart. ACEDeleteRelators also returns  the
new relator list. Use ACERelators (see ACERelators)  to  determine
the current relator list.
ACEDeleteSubgroupGenerators( i, list ) F
ACEDeleteSubgroupGenerators( list ) F
for the ith (or  default)  interactive  ACE  process  started  by
ACEStart, delete list from the  current  subgroup  generators,  if
list is a list of words in the  group  generators,  or  those  current
subgroup generators indexed by the integers in list, if list is  a
list  of  positive  integers,  and  automatically  invoke  ACEStart.
ACEDeleteSubgroupGenerators also returns the new subgroup  generator
list.  Use  ACESubgroupGenerators  (see ACESubgroupGenerators)  to
determine the current subgroup generator list.
ACECosetCoincidence( i, n ) F
ACECosetCoincidence( n ) F
for the ith (or  default)  interactive  ACE  process  started  by
ACEStart, return the representative of coset n, where n must  be
a positive integer, and add  it  to  the  subgroup  generators;  i.e.,
equates  this  coset  with  coset  1,  the  subgroup.   ACERedo   is
automatically invoked.
ACERandomCoincidences( i, subindex ) F
ACERandomCoincidences( subindex ) F
ACERandomCoincidences( i, [subindex] ) F
ACERandomCoincidences( [subindex] ) F
ACERandomCoincidences( i, [subindex, attempts] ) F
ACERandomCoincidences( [subindex, attempts] ) F
for the ith (or  default)  interactive  ACE  process  started  by
ACEStart, attempt up to attempts (or, in the first four forms,  8)
times to find nontrivial subgroups with index a multiple of subindex
by repeatedly making random coset numbers coincident with coset 1  and
seeing what happens. The starting coset table must be  non-empty,  but
must  not  be   complete   (use   ACERandomlyApplyCosetCoincidence
(see ACERandomlyApplyCosetCoincidence)  if  your  table  is  already
complete).  For  each  attempt,  by  applying  ACE's  rc   option
(see option rc) random coset representatives are repeatedly added to
the subgroup and the enumeration redone. If the  table  becomes  too
small, the  attempt  is  aborted,  the  original  subgroup  generators
restored, and another attempt made. If an attempt succeeds,  then  the
new set of subgroup generators  is  retained.  ACERandomCoincidences
returns   the   list   of   new   subgroup   generators   added.   Use
ACESubgroupGenerators (see ACESubgroupGenerators) to determine the
current subgroup generator list.
Notes: 
ACERandomCoincidences may add subgroup generators even if it  failed
to  determine  a  nontrivial  subgroup  with  index  a   multiple   of
subindex; in such a case, the original status  may  be  restored  by
applying                                 ACEDeleteSubgroupGenerators
(see ACEDeleteSubgroupGenerators)  with   the   list   returned   by
ACERandomCoincidences.
ACERandomCoincidences applies the rc option (see option  rc)  of
ACE which takes  the  line  that  if  an  enumeration  has  already
obtained a finite index then either, subindex is already  a  divisor
of that finite index, or the request is impossible. Thus an invocation
of ACERandomCoincidences, in the  case  where  the  coset  table  is
already complete, is an error.
Guru  Notes:  A  coset  can  have  many  different  representatives.
Consider              running              ACEStandardCosetNumbering
(see ACEStandardCosetNumbering) before  ACERandomCoincidences,  to
canonicise the table and the representatives.
ACERandomlyApplyCosetCoincidence( i [: controlOptions]) F
ACERandomlyApplyCosetCoincidence( [: controlOptions]) F
for the ith (or  default)  interactive  ACE  process  started  by
ACEStart, try to find a larger proper subgroup (i.e. a  subgroup  of
smaller   but    nontrivial    index),    by    repeatedly    applying
ACECosetCoincidence  (see ACECosetCoincidence)  and  seeing   what
happens;  ACERandomlyApplyCosetCoincidence  returns  the   (possibly
empty) list of new subgroup generators added. The starting coset table
must    already    be    complete     (use     ACERandomCoincidences
(see ACERandomCoincidences) if your table is not already  complete).
ACERandomlyApplyCosetCoincidence provides the following four options
(controlOptions).
subindex := subindex
hibound := hibound
lobound := lobound
attempts := attemptsACECosetCoincidence should be at most attempts; attempts must be
a positive integer.
By default, subindex =  1,  hibound  is  the  existing  subgroup
index, lobound = 1 and attempts = 8. If after an  attempt  the
new index is a multiple of subindex, less than hibound and greater
than lobound then the  process  terminates  (and  the  list  of  new
subgroup generators is returned). Otherwise, if an attempt  reaches  a
stage where the criteria cannot be satisfied, the attempt is  aborted,
the original subgroup generators restored, and another  attempt  made.
If  no  attempt  is  successful  an  empty  list  is   returned.   Use
ACESubgroupGenerators (see ACESubgroupGenerators) to determine the
current subgroup generator list.
ACEConjugatesForSubgroupNormalClosure( i ) F
ACEConjugatesForSubgroupNormalClosure() F
ACEConjugatesForSubgroupNormalClosure( i : add ) F
ACEConjugatesForSubgroupNormalClosure(: add ) F
for the ith (or  default)  interactive  ACE  process  started  by
ACEStart, test each conjugate of a subgroup  generator  by  a  group
generator for membership in the subgroup,  and  return  the  (possibly
empty) list of conjugates that were determined to not  belong  to  the
subgroup (coset 1); and,  if  called  with  the  add  option,  these
conjugates are also added to the existing list of subgroup generators.
Notes: A conjugate of a subgroup generator is tested for  membership
of the subgroup, by checking whether it can be traced from coset 1  to
coset 1  (see  ACETraceWord: ACETraceWord).  For  an  incomplete
coset  table,  such  a  trace  may  not  complete,   in   which   case
ACEConjugatesForSubgroupNormalClosure may return an empty list  even
though the subgroup is not normally closed within the group.
The add option does not guarantee that the resultant  subgroup  is
normally closed. It is still possible  that  some  conjugates  of  the
newly added subgroup generators will not be elements of the subgroup.
Example:
To      demonstrate      the      usage      and      features      of
ACEConjugatesForSubgroupNormalClosure, let us  consider  an  example
where we know pretty well what to expect.
Let G be the group, isomorphic to the symmetric  group  S6,  with
the presentation
| 
 | 
First we start an enumeration with max set to 80.
gap> F := FreeGroup( "a", "b" );; gap> a := F.1;; b := F.2;; gap> fgens := GeneratorsOfGroup( F );; gap> rels := [ a^2, b^6, (a*b^-1*a*b)^3, (a*b^-1*a*b^2)^4, (a*b)^5, > (a*b^-2*a*b^2)^2 ];; gap> sgens := [ a*b^3 ];; gap> i := ACEStart( fgens, rels, sgens : max := 80 );; gap> IsCompleteACECosetTable( i ); false gap> ACEConjugatesForSubgroupNormalClosure( i : add ); #I ACEConjugatesForSubgroupNormalClosure: All (traceable) conjugates in subgp [ ]
Though we know that H is not equal to its normal closure, we did not
get any new elements (we had warned  above  of  such  a  possibility).
Apparently our incomplete table is too small. So let us increase max
to 100 and continue.
gap> ACEContinue( i : max := 100 );; gap> IsCompleteACECosetTable( i ); false gap> ACEConjugatesForSubgroupNormalClosure( i : add ); [ b^-1*a*b^4 ] gap> IsCompleteACECosetTable( i ); true gap> ACEStats( i ).index; 20
This time we got a new element, and after adding it  to  the  subgroup
generators  we  obtained  a  complete  table.  However  the  resulting
subgroup need not yet be the normal closure of H  (and  in  fact  we
know that it is not). So we continue with another call to the function
ACEConjugatesForSubgroupNormalClosure.
gap> ACEConjugatesForSubgroupNormalClosure( i : add ); [ b^-2*a*b^5, b*a*b^2 ] gap> ACEStats( i ).index; 2
Now we have the index that we expected. Another call to  the  function
ACEConjugatesForSubgroupNormalClosure  should  not  yield  any  more
conjugates. We ensure that this is indeed the case  and  then  display
the resulting list of subgroup generators.
gap> ACEConjugatesForSubgroupNormalClosure( i : add ); #I ACEConjugatesForSubgroupNormalClosure: All (traceable) conjugates in subgp [ ] gap> ACESubgroupGenerators( i ); [ a*b^3, b*a*b^2, b^-1*a*b^4, b^-2*a*b^5 ]
For those familiar with the  workings  of  the  ACE  standalone  we
provide primitive read/write tools to  communicate  directly  with  an
interactive ACE process,  started  via  ACEStart  (possibly  with
argument 0, but this is not essential). For the most part, it is up to
the user to translate the output  strings  from  ACE  into  a  form
useful in GAP. However, after the group generators,  relators,  and
subgroup  generators  have  been  set  in  the  ACE  process,   via
ACEWrite,    invocations    of    any    of     ACEGroupGenerators
(see ACEGroupGenerators),     ACERelators     (see ACERelators),
ACESubgroupGenerators       (see ACESubgroupGenerators),        or
ACEParameters (see ACEParameters) will establish the corresponding
GAP values.  Be  warned  though,  that  unless  one  of  the  modes
ACEStart  (without  a  zero  argument;  see ACEStart),   ACERedo
(see ACERedo)  or  ACEContinue   (see ACEContinue),   or   their
equivalent  for  the  standalone   ACE   (start;,   redo;,   or
continue;), has been invoked since the last change of any  parameter
options (see ACEParameterOptions), some of the  values  reported  by
ACEParameters may well be incorrect.
ACEWrite( i, string ) F
ACEWrite( string ) F
write string to the ith or  default  interactive  ACE  process;
string must be in exactly the form the  ACE  standalone  expects.
The command is  echoed  via  Info  at  InfoACE  level  4  (with  a
``ToACE> '' prompt); i.e. SetInfoACELevel(4);  will  allow  you to
see what is transmitted to the ACE binary. ACEWrite returns true
if successful in writing to the stream of the interactive ACE process,
and fail otherwise.
Note:
If ACEWrite returns fail (which means that the ACE process  has
died), you may like to try resurrecting the interactive ACE process
via ACEResurrectProcess (see ACEResurrectProcess).
ACERead( i ) F
ACERead() F
read a complete line of ACE  output,  from  the  ith  or  default
interactive ACE process, if there is output to be read and  returns
fail otherwise. When successful, the line is returned  as  a  string
complete with trailing newline  character.  Please  note  that  it  is
possible to be ``too quick'' (i.e. the return  can  be  fail  purely
because the output from ACE is not there  yet),  but  if  ACERead
finds any output at all, it waits for a complete line.
ACEReadAll( i ) F
ACEReadAll() F
read and return as many complete lines of ACE  output,  from  the
ith or default interactive ACE process, as there are to be  read,
at the time of the call, as a list  of  strings  with  the  trailing
newlines removed and returns the empty  list  otherwise.  ACEReadAll
also writes each line read via Info at InfoACE level  3.  Whenever
ACEReadAll finds only a partial line,  it  waits  for  the  complete
line, thus increasing the probability that it  has  captured  all  the
output to be had from ACE.
ACEReadUntil( i, IsMyLine ) F
ACEReadUntil( IsMyLine ) F
ACEReadUntil( i, IsMyLine, Modify ) F
ACEReadUntil( IsMyLine, Modify ) F
read complete lines of  ACE  output,  from  the  ith  or  default
interactive ACE process, ``chomps'' them (i.e. removes any trailing
newline character), emits them to Info at  InfoACE  level  3,  and
applies the function Modify (where Modify  is  just  the  identity
map/function for the first two forms) until a ``chomped'' line  line
for which IsMyLine( Modify(line)  )  is  true.  ACEReadUntil
returns the list of Modify-ed ``chomped'' lines read.
Notes: When provided by the user, Modify should be a function that accepts a single string argument.
IsMyLine should be a function that is able to accept the output of Modify (or take a single string argument when Modify is not provided) and should return a boolean.
If IsMyLine( Modify(line) ) is never true, ACEReadUntil will
wait indefinitely.
[Up] [Previous] [Next] [Index]
ACE manual