%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  otheroptions.tex    ACE appendix - other options     Alexander Hulpke
%W                                                      Joachim Neub"user
%W                                                            Greg Gamble
%%
%H  $Id: otheroptions.tex,v 1.19 2006/01/26 16:15:05 gap Exp $
%%
%Y  Copyright (C) 2000  Centre for Discrete Mathematics and Computing
%Y                      Department of Information Tech. & Electrical Eng.
%Y                      University of Queensland, Australia.
%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Chapter{Other ACE Options}

Here we list all the known {\ACE} options not provided  earlier.  Most
of the options provided here have  interactive  function  alternatives
(each such alternative is noted at the end of the  section  describing
the corresponding option  and  introduced  by  ``*INTERACTIVELY*,  use
\dots''). A few options have only limited usefulness from {\GAP}; many
options, users will normally only wish to use if generating  an  input
file,  by  using  the  option  `aceinfile'  (see~"option  aceinfile").
However all  options  here  are  functional,  both  interactively  and
non-interactively.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Experimentation Options}

\beginitems

\>`aep:=<val>'{option aep}@{option `aep'}&
Runs the enumeration for `a'll `e'quivalent `p'resentations;
<val> is in the integer range 1 to 7.

The `aep' option runs  an  enumeration  for  combinations  of  relator
ordering, relator rotations, and relator inversions.

The argument <val> is considered as a binary number.  Its  three  bits
are treated as flags, and control relator rotations (the  $2^0$  bit),
relator inversions (the $2^1$ bit) and relator  orderings  (the  $2^2$
bit),  respectively;  where  $1$  means  ``active''  and   $0$   means
``inactive''. (See below for an example).

The `aep' option first performs a ``priming run'' using the options as
they stand. In particular,  the  `asis'  and  `messages'  options  are
honoured.

It then turns `asis' on and `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 a new ``record'' is found,
the relators  used  and  the  summary  result  line  is  printed.  See
Appendix~"The Meanings of ACE's output messages" for a  discussion  of
the statistics `m' and `t'. To observe these messages either  set  the
`InfoLevel' of `InfoACE' to 3 or non-interactively you can peruse  the
{\ACE} output file (see~"option aceoutfile").

Normally when a non-interactive {\ACE} interface function  is  called,
the option `start' (see~"option start"), is quietly inserted after all
the options provided by the user, to  initiate  a  coset  enumeration.
Since the `aep' option invokes an enumeration, the quiet insertion  of
the `start' option is neither needed nor done, when a  non-interactive
{\ACE} interface function is called with the `aep' option.

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 `aep' option, (not that  a  non-interactive
user cares).

As discussed by Cannon, Dimino, Havas  and  Watson  \cite{CDHW73}  and
Havas and Ramsay \cite{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 file:

\beginlist%unordered

\item{--}  the number of runs which yielded a finite index; 

\item{--}  the total number of runs (excluding the priming run); and 

\item{--}  the range of values observed for `m' and `t'.

\endlist

As an example (drawn from the discussion in \cite{HR99a}) consider the
enumeration   of   the   $448$   coset   numbers   of   the   subgroup
$\langle  a^2,a^{-1}b \rangle$ of the group
$$
(8,7 \mid 2,3) 
    = \langle a,b \mid a^8 = b^7 = (ab)^2 = (a^{-1}b)^3 = 1 \rangle.
$$
There are $4!=24$  relator  orderings  and  $2^4=16$  combinations  of
relator or inverted relator. Exponents are  taken  into  account  when
rotating relators, so the relators given give rise to 1, 1,  2  and  2
rotations respectively, for a total of $1.1.2.2=4$  combinations.  So,
for  `aep'  =  $7$   (resp.~$3$),   $24.16.4=1536$   (resp.~$16.4=64$)
equivalent presentations are tested.

*Notes:*
There is no way to stop the `aep'  option  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  `rep'
command.

*INTERACTIVELY*,            use             `ACEAllEquivPresentations'
(see~"ACEAllEquivPresentations").

\>`rep:=<val>'{option rep}@{option `rep'}
\>`rep:=[<val>, <Npresentations>]'{option rep}@{option `rep'}&
Run the enumeration for `r'andom `e'quivalent `p'resentations;
<val> is in the integer range 1 to 7;
<Npresentations> must be a positive integer.

The `rep' (random equivalent  presentations)  option  complements  the
`aep'  option.  It  generates  and  tests   some   random   equivalent
presentations. The argument <val>  acts  as  for  `aep'.  It  is  also
possible to set the number <Npresentations>  of  random  presentations
used (by default, eight  are  used),  by  using  the  extended  syntax
`rep:=[<val>,<Npresentations>]'.

The routine first  turns  `asis'  on  and  `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.  To  observe  these
messages either set the `InfoLevel' of `InfoACE'  to  at  least  3  or
non-interactively you can peruse the {\ACE} output  file  (see~"option
aceoutfile").

Normally when a non-interactive {\ACE} interface function  is  called,
the option `start' (see~"option start"), is quietly inserted after all
the options provided by the user, to  initiate  a  coset  enumeration.
Since the `rep' option invokes an enumeration, the quiet insertion  of
the `start' option is neither needed nor done, when a  non-interactive
{\ACE} interface function is called with the `rep' option.

*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 `rep' command  completes,  the  presentation  active  is  the
*last* one generated, (not that the non-interactive user cares).

*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 `aep', we can start up multiple copies of `aep'
at random points in the  search-space.  Manually  generating  `random'
equivalent presentations to serve as starting-points  is  tedious  and
error-prone. The `rep' option provides a simple solution;  simply  run
`rep := 7' before `aep := 7'.

*INTERACTIVELY*,           use           `ACERandomEquivPresentations'
(see~"ACERandomEquivPresentations").

\enditems

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Options that Modify a Presentation}

\beginitems

\>`group:=<grpgens>'{option group}@{option `group'}&
Defines the `group' generators; <grpgens> should be an  integer  (that
is the number of generators) or a string that is the concatenation of,
or a list of, single-lowercase-letter group generator  names,  i.e.~it
should be in a form suitable  for  the  {\ACE}  binary  to  interpret.
(Shortest abbreviation: `gr'.)

The group generators should normally be input as one of the  arguments
of an {\ACE} interface function, though this option may be useful when
`ACEStart' (see~"ACEStart") is called with the single argument 0. This
option may also be useful for re-using an interactive  process  for  a
new enumeration, rather than using `ACEQuit' to kill the  process  and
`ACEStart' to initiate a new process.  If  the  generators  each  have
names that as strings are single lowercase letters, those same strings
are used to represent the same generators by {\ACE}; otherwise, {\ACE}
will represent each generator by  an  integer,  numbered  sequentially
from 1.

To convert a {\GAP} list <fgens> of free group generators into a  form
suitable   for   the   `group'   option,   use    the    construction:
`ToACEGroupGenerators(<fgens>)'  (see~"ToACEGroupGenerators").  It  is
*strongly recommended* that users  of  the  `group'  option  use  this
construction.

*Notes:*
Any use of the  `group'  command  which  actually  defines  generators
invalidates any previous enumeration, and stays in  effect  until  the
next `group' command. Any words for the  group  or  subgroup  must  be
entered using the nominated generator format, and  all  printout  will
use this format. A valid set of generators is the minimum  information
necessary before {\ACE} will attempt an enumeration.

*Guru Notes:*
The columns of the coset table are allocated in the same order as  the
generators are listed, insofar as this is  possible,  given  that  the
first two columns must be  a  generator/inverse  pair  or  a  pair  of
involutions. The ordering of the columns can, in  some  cases,  affect
the definition sequence of cosets and  impact  the  statistics  of  an
enumeration.

\>`relators:=<relators>'{option relators}@{option `relators'}&
Defines the group `relators'; <relators> must be a string or  list  of
strings that the {\ACE} binary can interpret as  words  in  the  group
generators. (Shortest abbreviation: `rel'.)

The group relators should normally be input as one of the arguments of
an {\ACE} interface function, but  this  option  may  occasionally  be
useful with interactive processes (see~"option group"). If  <wordList>
is an empty list, the group is free.

To convert a  {\GAP}  list  <rels>  of  relators  in  the  free  group
generators <fgens> into a form suitable for the `relators' option, use
the construction: `ToACEWords(<fgens>, <rels>)' (see~"ToACEWords").

\>`generators:=<subgens>'{option  generators}@{option `generators'}&
Defines the subgroup `generators'; <subgens> must be a string or  list
of strings that the {\ACE} binary can interpret as words in the  group
generators. (Shortest abbreviation: `gen'.)

The subgroup generators  should  normally  be  input  as  one  of  the
arguments of  an  {\ACE}  interface  function,  but  this  option  may
occasionally  be  useful  with  interactive   processes   (see~"option
group"). By default, there are no subgroup generators and the subgroup
is trivial. This command allows a list of subgroup generating words to
be entered.

To convert a {\GAP} list <sgens> of subgroup generators  in  the  free
group generators <fgens> into a form  suitable  for  the  `generators'
option,   use   the   construction:   `ToACEWords(<fgens>,   <sgens>)'
(see~"ToACEWords").

\>`sg:=<subgens>'{option sg}@{option `sg'}&
Adds the words in <subgens> to  any  `s'ubgroup  `g'enerators  already
present; <subgens> must be a string or list of strings that the {\ACE}
binary can interpret as words in the group generators.

The enumeration must  be  (re)`start'ed  or  `redo'ne,  it  cannot  be
`continu'ed.

To convert a {\GAP} list <sgens> of subgroup generators  in  the  free
group generators <fgens> into a form  suitable  for  the  `generators'
option,   use   the   construction:   `ToACEWords(<fgens>,   <sgens>)'
(see~"ToACEWords").

*INTERACTIVELY*,            use             `ACEAddSubgroupGenerators'
(see~"ACEAddSubgroupGenerators").

\>`rl:=<relators>'{option rl}@{option `rl'}&
Appends the `r'elator  `l'ist  <relators>  to  the  existing  list  of
relators present; <relators> must be a string or list of strings  that
the {\ACE} binary can interpret as words in the group generators.

The enumeration must  be  (re)`start'ed  or  `redo'ne,  it  cannot  be
`continu'ed.

To convert a  {\GAP}  list  <rels>  of  relators  in  the  free  group
generators <fgens> into a form suitable for the `rl' option,  use  the
construction: `ToACEWords(<fgens>, <rels>)' (see~"ToACEWords").

*INTERACTIVELY*, use `ACEAddRelators' (see~"ACEAddRelators").

\>`ds:=<list>'{option ds}@{option `ds'}&
`D'eletes `s'ubgroup generators; <list> must be  a  list  of  positive
integers.

This command  allows  subgroup  generators  to  be  deleted  from  the
presentation. If the generators are numbered from 1 in the output  of,
say, the `sr' command (see~"option sr"), then the generators listed in
`<list>' are deleted; `<list>' must be a strictly increasing sequence.

*INTERACTIVELY*,           use           `ACEDeleteSubgroupGenerators'
(see~"ACEDeleteSubgroupGenerators").

\>`dr:=<list>'{option dr}@{option `dr'}&
`D'eletes relators; <list> must be a list of positive integers.

This  command  allows  group  relators  to   be   deleted   from   the
presentation. If the relators are numbered from 1 in  the  output  of,
say, the `sr' command (see~"option sr"), then the relators  listed  in
`<list>' are deleted; `<list>' must be a strictly increasing sequence.

*INTERACTIVELY*, use `ACEDeleteRelators' (see~"ACEDeleteRelators").

\>`cc:=<val>'{option cc}@{option `cc'}&
Makes `c'oset <val>  `c'oincide  with  coset  1;  <val>  should  be  a
positive integer.

Prints out the representative of coset `<val>', and  adds  it  to  the
subgroup generators; i.e., forces coset `<val>' to coincide with coset
1, the subgroup.

*INTERACTIVELY*,               use               `ACECosetCoincidence'
(see~"ACECosetCoincidence").

\>`rc:=<val>'{option rc}@{option `rc'}
\>`rc:=[<val>]'{option rc}@{option `rc'}
\>`rc:=[<val>, <attempts>]'{option rc}@{option `rc'}&
Enforce `r'andom `c'oincidences; <val> and <attempts> must be positive
integers.

This option attempts upto <attempts> (or,  in  the  first  and  second
forms, 8) times to find nontrivial subgroups with index a multiple  of
<val> by repeatedly making random coset numbers coincident with  coset
1 and seeing what happens. The starting coset table must be non-empty,
but should not be complete. For each attempt, we repeatedly add random
coset representatives to the subgroup and `redo' the  enumeration.  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.

*Guru Notes:*
A coset number can have many different coset representatives. Consider
running `standard' before `rc', to canonicise the table and hence  the
coset representatives.

*INTERACTIVELY*,              use              `ACERandomCoincidences'
(see~"ACERandomCoincidences").

\enditems

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Mode Options}

\beginitems

\>`mode'{option mode}@{option `mode'}&
Prints the possible enumeration `mode's.
(Shortest abbreviation: `mo'.)

Prints the possible  enumeration  `mode's  (i.e.~which  of  `continu',
`redo' or `start' are possible (see~"option  continu",  "option  redo"
and "option start").

*INTERACTIVELY*, use `ACEModes' (see~"ACEModes").

\>`begin'{option begin}@{option `begin'}
\>`start'{option start}@{option `start'}&
Start an enumeration. (Shortest abbreviation of `begin' is `beg'.)

Any existing information in the table is cleared, and the  enumeration
starts from coset 1 (i.e., the subgroup).

Normally when a non-interactive {\ACE} interface function  is  called,
the option `start' (see~"option start"), is quietly inserted after all
the options provided by the user, to  initiate  a  coset  enumeration;
however, this is not done, if the user  herself  supplies  either  the
`begin' or `start' option.

*INTERACTIVELY*, use `ACEStart' (see~"ACEStart").

\>`check'{option check}@{option `check'}
\>`redo'{option redo}@{option `redo'}&
`Redo' an extant enumeration, using the current parameters.

As opposed to `start' (see~"option start"), which clears  an  existing
coset table, any existing information in the table  is  retained,  and
the enumeration is restarted from coset 1 (i.e., the subgroup).

*Notes:*
This option is really intended for the case where additional  relators
(option `rl'; see~"option  rl")  and/or  subgroup  generators  (option
`sg'; see~"option sg") have been introduced. The current table,  which
may be incomplete  or  exhibit  a  finite  index,  is  still  *valid*.
However, the additional data may allow the enumeration to complete, or
cause a collapse to a smaller index.

*INTERACTIVELY*, use `ACERedo' (see~"ACERedo").

\atindex{option continue!deprecated: use continu}%
{@option \noexpand`continue'!deprecated: use \noexpand`continu'}
\>`continu'{option continu}@{option `continu'}&
`Continu'es the current enumeration, building upon the existing table.
(Shortest abbreviation: `cont'.)

If a previous run stopped without producing a finite index you can, in
principle, change any of the parameters and `continu'e on. Of  course,
if you make any changes which invalidate the current table, you  won't
be allowed to `continue',  although  you  may  be  allowed  to  `redo'
(see~"option redo"). If `redo' is not  allowed,  you  must  re-`start'
(see~"option start").

*Note:* The {\ACE} standalone allows the option `continue',  but  this
is (as of {\GAP} 4.3) a {\GAP} keyword, and so {\GAP} users  must  use
(mixed-case abbreviations of) `continu'.

*INTERACTIVELY*, use `ACEContinue' (see~"ACEContinue").

\enditems

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Options that Interact with the Operating System}

\beginitems

\>`ai'{option ai}@{option `ai'}
\>`ai:=<filename>'{option ai}@{option `ai'}&
`A'lter `i'nput to standard input or <filename>; <filename> must be  a
string.

By default, commands to {\ACE} are read from standard input (i.e., the
keyboard). With no value `ai' causes {\ACE} to revert to reading  from
standard input; otherwise, the `ai' command closes the  current  input
file,  and  opens  `<filename>'  as  the  source   of   commands.   If
`<filename>' can't be opened, input reverts to standard input.

*Notes:*
If you switch to taking input from (another) file, remember to  switch
back before the end of that file; otherwise the `EOF' there will cause
{\ACE} to terminate.

\>`bye'{option bye}@{option `bye'}
\>`exit'{option exit}@{option `exit'}
\>`qui'{option qui}@{option `qui'}&
Quit {\ACE}. (Shortest abbreviation of `qui' is `q'.)

This quits {\ACE} nicely, printing the date and  the  time.  An  `EOF'
(end-of-file;  i.e.,  `\^{}d')  has  the  same   effect,   so   proper
termination occurs if {\ACE} is taking its input from a script file.

Note  that  `qui'  actually  abbreviates  the   corresponding   {\ACE}
directive `quit', but since `quit' is  a  {\GAP}  keyword  it  is  not
available via the {\GAP} interface to {\ACE}.

*INTERACTIVELY*, use `ACEQuit' (see~"ACEQuit").

\>`system:=<string>'{option system}@{option `system'}&
Does a shell escape, to execute <string>; <string> must be a string.
(Shortest abbreviation: `sys'.)

Since {\GAP} already provides `Exec()' for this purpose,  this  option
is unlikely to have a use.

\enditems

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Query Options}

\beginitems

\>`cycles'{option cycles}@{option `cycles'}&
Prints out the table in `cycles'. (Shortest abbreviation: `cy'.)

This option prints out the permutation representation.

*INTERACTIVELY*, use `ACECycles' (see~"ACECycles").

\>`dump'{option dump}@{option `dump'}
\>`dump:=<level>'{option dump}@{option `dump'}
\>`dump:=[<level>]'{option dump}@{option `dump'}
\>`dump:=[<level>, <detail>]'{option dump}@{option `dump'}&
`Dump' the internal variables of {\ACE}; <level> must be an integer in
the range 0 to 2, and <detail> must be 0 or 1.
(Shortest abbreviation: `d'.)

The value of <level> determines which of the three levels of {\ACE} to
dump. (You will need to read the standalone manual  `acce3001.dvi'  in
the `standalone-doc' directory 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 form (with no arguments)
selects `<level> = 0, <detail> = 0'. The second form of  this  command
makes `<detail> = 0'. This option is intended for  gurus;  the  source
code should be consulted to see what the output means.

*INTERACTIVELY*, use `ACEDumpVariables' (see~"ACEDumpVariables").

\>`help'{option help}@{option `help'}&
Prints the {\ACE} help screen. (Shortest abbreviation: `h'.)

This option prints the list of options of the {\ACE} binary. Note that
this list is longer than a standard screenful.

\>`nc'{option nc}@{option `nc'}
\>`nc:=<val>'{option nc}@{option `nc'}
\>`normal'{option normal}@{option `normal'}
\>`normal:=<val>'{option normal}@{option `normal'}&
Check or attempt to enforce normal closure; <val> must be 0 or 1.

This option tests the subgroup for normal closure within the group. If
a conjugate of a subgroup generator by a generator, is  determined  to
belong to a coset other than coset 1, it is printed out, and if `<val>
=  1',  then  any  such  conjugate  is  also  added  to  the  subgroup
generators. With no argument or if `<val> = 0', {\ACE}  does  not  add
any new subgroup generators.

*Notes:*
The method of determination of  whether  a  conjugate  of  a  subgroup
generator is in the subgroup, is by testing whether it can  be  traced
from coset 1 to coset 1  (see  `trace':~"option trace").

The resultant subgroup need not be  normally  closed  after  executing
option `nc'  with  the  value  1.  It  is  still  possible  that  some
conjugates of the newly added subgroup generators will not be elements
of the subgroup.

*INTERACTIVELY*,      use      `ACEConjugatesForSubgroupNormalClosure'
(see~"ACEConjugatesForSubgroupNormalClosure").

\>`options'{option options}@{option `options'}&
Dumps version information of the {\ACE} binary.
(Shortest abbreviation: `opt'.)

A rather unfortunate name for an option; this command dumps details of
the ``options'' included in the version  of  {\ACE}  when  the  {\ACE}
binary was compiled.

A typical output, is as follows:

\begintt
Executable built:
  Sat Feb 27 15:57:59 EST 1999
Level 0 options:
  statistics package = on
  coinc processing messages = on
  dedn processing messages = on
Level 1 options:
  workspace multipliers = decimal
Level 2 options:
  host info = on
\endtt

*INTERACTIVELY*    and    non-interactively,    use    the     command
`ACEBinaryVersion();' (see~"ACEBinaryVersion") for  this  information,
instead, unless you want it in an {\ACE} standalone input file.

\>`oo:=<val>'{option oo}@{option `oo'}
\>`order:=<val>'{option order}@{option `order'}&
Print a coset representative of a coset number with order  a  multiple
of <val> modulo the subgroup; <val> must be an integer.

This option finds a coset with order a multiple  of  `|<val>|'  modulo
the subgroup, and prints out its coset representative.  If  `<val>  \<
0', then all coset numbers meeting the  requirement  are  printed.  If
`<val> > 0', then just the first coset number meeting the  requirement
is printed. Also, `<val> = 0' is permitted; this special value effects
the printing of the orders (modulo the subgroup) of all coset numbers.

*INTERACTIVELY*,  use  `ACEOrders'  (see~"ACEOrders"),  for  the  case
`<val> = 0', or `ACEOrder' (see~"ACEOrder"), otherwise.

\>`sr'{option sr}@{option `sr'}
\>`sr:=<val>'{option sr}@{option `sr'}&
Print out parameters of the current presentation;  <val>  must  be  an
integer in the range 0 to 5.

No argument, or `<val> = 0', prints out the `Group Name', the  group's
`relators', `Subgroup Name' and the subgroup's `generators'. If `<val>
= 1', then the `Group Generators' and the current setting of the ``run
parameters'' is also  printed.  The  printout  is  the  same  as  that
produced at the start of a run  when  option  `messages'  (see~"option
messages") is non-zero. Also, <val> equal to 2, 3, 4, or 5  print  out
just the `Group Name', just the group's `relators', just the `Subgroup
Name', or just the subgroup's `generators', respectively.

*Notes:*
The `sr' option should  only  be  used  *after*  an  enumeration  run;
otherwise, the value 0 for some options will be unreliable. To  ensure
this occurs non-interactively, ensure one of the options that  invokes
an enumeration: `start' (see~"option  start")  or  `aep'  (see~"option
aep") or `rep' (see~"option rep"), precedes the `sr' option. (When  an
enumeration-invoking option is included  non-interactively  the  quiet
inclusion step of the `start' option is omitted.)

*INTERACTIVELY*, use `ACEGroupGenerators'  (see~"ACEGroupGenerators"),
`ACERelators'   (see~"ACERelators"),   `ACESubgroupGenerators'    (see
"ACESubgroupGenerators"), and `ACEParameters' (see~"ACEParameters").

\>`print'{option print}@{option `print'}
\>`print:=<val>'{option print}@{option `print'}
\>`print:=[<val>]'{option print}@{option `print'}
\>`print:=[<val>, <last>]'{option print}@{option `print'}
\>`print:=[<val>, <last>, <by>]'{option print}@{option `print'}&
Compact and print the coset table;  <val>  must  be  an  integer,  and
<last> and <by> must be positive integers.
(Shortest abbreviation: `pr'.)

In the first (no value) form, `print' prints the entire  coset  table,
without orders or coset  representatives.  In  the  second  and  third
forms, the absolute value of <val> is taken to be the last line of the
table to be printed (and 1 is taken to be the first);  in  the  fourth
and fifth forms, `|<val>|' is taken to be the first line of the  table
to be printed, and <last> is taken to be the number of the  last  line
to be printed. In the last  form,  the  table  is  printed  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 printed also.

*INTERACTIVELY*,              use               `ACEDisplayCosetTable'
(see~"ACEDisplayCosetTable").

\>`sc:=<val>'{option sc}@{option `sc'}
\>`stabilising:=<val>'{option stabilising}@{option `stabilising'}&
Print out the coset numbers whose elements normalise the subgroup; 
<val> must be an integer.
(Shortest abbreviation of `stabilising' is `stabil'.)

If `<val> > 0', the first `<val>' non-trivial (i.e.~other  than  coset
1) coset numbers whose elements normalise the subgroup are printed. If
`<val> = 0', all non-trivial coset numbers  whose  elements  normalise
the subgroup, plus their representatives, are printed.  If  `<val>  \<
0', the first  `|<val>|'  non-trivial  coset  numbers  whose  elements
normalise the subgroup, plus their representatives, are printed.

*Note:*
The name of this option is an historical hangover. It is named for the
property that elements that ``normalise'' a subgroup, may be  said  to
``stabilise'' that subgroup when they act  ``by  conjugation''.  Also,
the option `normal' (see~"option normal") already performs a different
function.

*INTERACTIVELY*,         use          `ACECosetsThatNormaliseSubgroup'
(see~"ACECosetsThatNormaliseSubgroup").

\>`statistics'{option statistics}@{option `statistics'}
\>`stats'{option stats}@{option `stats'}&
Dump enumeration statistics.
(Shortest abbreviation of `statistics' is `stat'.)

If the statistics package is compiled into the {\ACE} code,  which  it
is by default (see the `options'~"option options" option),  then  this
option  dumps  the  statistics  accumulated  during  the  most  recent
enumeration. See the `enum.c' source  file  for  the  meaning  of  the
variables.

*INTERACTIVELY*, use `ACEDumpStatistics' (see~"ACEDumpStatistics").

\>`style'{option style}@{option `style'}&
Prints the current enumeration style.

This option prints the current enumeration style, as deduced from  the
current `ct' and `rt' parameters (see~"Enumeration Style").

*INTERACTIVELY*, use `ACEStyle' (see~"ACEStyle").

\>`tw:=[<val>, <word>]'{option tw}@{option `tw'}
\>`trace:=[<val>, <word>]'{option trace}@{option `trace'}&
Trace `<word>' through the coset table,  starting  at  coset  `<val>';
<val> must be a positive integer, and <word> must be  a  word  in  the
group generators.

This option prints the final coset number of the trace, if  the  trace
completes.

*INTERACTIVELY*, use `ACETraceWord' (see~"ACETraceWord").

\enditems

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Options that Modify the Coset Table}

\beginitems

\index{dead coset (number)}
\>`recover'{option recover}@{option `recover'}
\>`contiguous'{option contiguous}@{option `contiguous'}&
`Recover' space used by dead coset numbers.
(Shortest  abbreviation  of  `recover'   is   `reco',   and   shortest
abbreviation of `contiguous' is `contig'.)

This option invokes the compaction routine on the table to recover the
space used by any dead coset numbers. A `CO' message line  is  printed
if any cosets were recovered, and a  `co'  line  if  none  were.  This
routine is called automatically if  the  `cycles',  `nc',  `print'  or
`standard' options (see~"option cycles", "option nc",  "option  print"
and "option standard") are invoked.

*INTERACTIVELY*, use `ACERecover' (see~"ACERecover").

\>`standard'{option standard}@{option `standard'}&
Compacts {\ACE}'s  coset  table  and  standardises  the  numbering  of
cosets, according to the `lenlex'  scheme  (see  Section~"Coset  Table
Standardisation Schemes"). (Shortest abbreviation: `st'.)

For a given ordering of the generators in the columns of the table, it
produces a canonical numbering of the cosets. This function  does  not
display the new table; use the `print' (see~"option print") for  that.
Such a table has the property that 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.

*Notes:*
In a `lenlex' standard 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, since {\ACE} avoids having an involutory generator in the  first
column when it can, this  lexicographic  order  does  not  necessarily
correspond with the order in which the generators were  first  put  to
{\ACE}. Two tables are equivalent only if their canonic forms are  the
same. Invoking this option directly does *not* affect the {\GAP} coset
table obtained via  `ACECosetTable';  use  the  `lenlex'  (see~"option
lenlex") option, if you want your table  `lenlex'  standardised.  (The
`lenlex' option restarts the enumeration, if it is necessary to ensure
the generators have not been rearranged.)

*Guru Notes:*
In  five  of  the  ten  standard  enumeration   strategies   of   Sims
\cite{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
interactive example).

*INTERACTIVELY*,            use            `ACEStandardCosetNumbering'
(see~"ACEStandardCosetNumbering").

\enditems

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Options for Comments}

\beginitems

\>`text:=<string>'{option text}@{option `text'}&
Prints <string> in the output; <string> must be a string.

This allows the user to add comments to the output from {\ACE}.

*Note:*
Please avoid using this option to insert comments starting with  three
asterisks: `***', since this string is used as a  sentinel  internally
in flushing output from {\ACE}.

\>`aceincomment:=<string>'{option aceincomment!different to option text}%
@{option `aceincomment'!different to option `text'}&
Prints comment <string> in the {\ACE} input; <string> must be a string.
(Shortest abbreviation: `aceinc'.)

This option prints the comment <string> behind a sharp sign (`\#')  in
the input to {\ACE}. Only useful  for  adding  comments  (that  {\ACE}
ignores) to standalone input files.

\enditems

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%E