options.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  options.tex         ACE documentation - options      Alexander Hulpke
%W                                                      Joachim Neub"user
%W                                                            Greg Gamble
%%
%H  $Id$
%%
%Y  Copyright (C) 2000  Centre for Discrete Mathematics and Computing
%Y                      Department of Information Tech. & Electrical Eng.
%Y                      University of Queensland, Australia.
%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Chapter{Options for ACE}

{\ACE} offers a wide range of options to  direct  and  guide  a  coset
enumeration, most of which  are  available  from  {\GAP}  through  the
interface provided by the {\ACE} Package.  We  describe  most  of  the
options available via the interface in this  chapter;  other  options,
termed strategies, are defined in Chapter~"Strategy Options for  ACE".
(Strategies are merely special options of {\ACE} that set a number  of
options described in this chapter, all at once.)  Yet  other  options,
for  which  interactive  function   alternatives   are   provided   in
Chapter~"Functions for Using ACE Interactively", or which most  {\GAP}
users are unlikely to  need,  are  described  in  Appendix~"Other  ACE
Options". From within a {\GAP} session, one may see the complete  list
of  {\ACE}  options,   after   loading   the   {\ACE}   Package   (see
Section~"Loading the ACE Package"), by typing

\beginexample
gap> RecNames(KnownACEOptions);
[ "default", "help", "check", "generators", "start", "path", "cycles", 
  "normal", "ds", "group", "subgroup", "relators", "order", "max", "rep", 
  "system", "silent", "time", "begin", "text", "options", "fill", 
  "aceinfile", "aceignore", "aceignoreunknown", "acenowarnings", "aceecho", 
  "aceincomment", "aceexampleoptions", "lenlex", "semilenlex", "incomplete", 
  "sg", "rl", "aep", "ai", "ao", "aceoutfile", "asis", "bye", "exit", "qui", 
  "cc", "cfactor", "ct", "redo", "compaction", "continu", "dmode", "dsize", 
  "dr", "dump", "easy", "echo", "enumeration", "felsch", "ffactor", "hard", 
  "hlt", "hole", "lookahead", "loop", "mendelsohn", "messages", "monitor", 
  "mode", "nc", "no", "oo", "pmode", "psize", "sr", "print", "purec", 
  "purer", "rc", "recover", "contiguous", "rfactor", "rt", "row", "sc", 
  "stabilising", "sims", "standard", "statistics", "stats", "style", "tw", 
  "trace", "workspace" ]

\endexample

(See Section~"The KnownACEOptions Record".) Also, from within a {\GAP}
session, you may use {\GAP}'s help browser (see Chapter~"ref:The  Help
System" in the  {\GAP}  Reference  Manual);  to  find  out  about  any
particular {\ACE} option, simply type: ```?option  <option>''',  where
<option> is one of the options listed above without any quotes, e.g.

\begintt
gap> ?option echo
\endtt

will display the section in this  manual  that  describes  the  `echo'
option.

We begin this chapter with several sections discussing the  nature  of
the options provided. Please spend some time reading  these  sections.
To continue onto the next section on-line using {\GAP}'s help browser,
type:

\begintt
gap> ?>
\endtt

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Passing ACE Options}

Options are passed to the {\ACE} interface functions in either of the
two usual mechanisms provided by {\GAP}, namely:

\beginlist%unordered

\item{--} options may be set globally using the function `PushOptions'
(see Chapter~"ref:Options Stack" in the {\GAP} Reference  Manual); or

\item{--} options may be appended to the argument list of any function
call, separated by a colon from the argument list  (see  "ref:Function
Calls" in the {\GAP} Reference Manual), in which case  they  are  then
passed on recursively to any subsequent inner function call, which may
in turn have options of their own.

\endlist

In general, if {\ACE} is to be used  interactively  one  should  avoid
using the global method of passing options. In fact, it is recommended
that prior to calling `ACEStart' the `OptionsStack' be empty.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Warnings regarding Options}

As mentioned above, one can set options globally  using  the  function
`PushOptions' (see Chapter~"ref:Options Stack" in the {\GAP} Reference
Manual); however, options pushed onto  `OptionsStack',  in  this  way,
remain there  until  an  explicit  `PopOptions()'  call  is  made.  In
contrast, options passed in the usual way behind a colon  following  a
function's arguments (see "ref:Function Calls" in the {\GAP} Reference
Manual)  are  local,  and  disappear  from  `OptionsStack'  after  the
function has executed successfully; nevertheless, a function, that  is
passed options this way, will also  see  any  global  options  or  any
options passed down recursively from functions calling that  function,
unless those  options  are  over-ridden  by  options  passed  via  the
function. Also note that duplication of  option  names  for  different
programs  may  lead   to   misinterpretations.   Since   a   non-empty
`OptionsStack' is potentially a mine-field for the  unwary  user,  the
function  `ResetOptionsStack'  (see~"ref:ResetOptionsStack"   in   the
Reference Manual) is now in the {\GAP} library and

\>FlushOptionsStack() F

introduced in version 3.001 of the {\ACE} Package to perform the  same
function, is now a synonym for `ResetOptionsStack'; it simply executes
`PopOptions()' until `OptionsStack' is empty.

However, `ResetOptionsStack' (or `FlushOptionsStack')  does  not  wipe
out the options already passed to an *interactive* {\ACE} process.  We
have provided `GetACEOptions' (see~"GetACEOptions") to keep  track  of
options that the {\ACE} binary process still considers  active,  which
may  or  may  not  be  still  on  the  `OptionsStack'.  There  is  the
interactive  `SetACEOptions'  (see~"SetACEOptions")  to  change   such
options, or,  of  course,  you  can  always  elect  to  use  `ACEQuit'
(see~"ACEQuit") and then start a new interactive {\ACE} process.

Finally,       if       `ACEIgnoreUnknownDefault       :=       false'
(see~"ACEIgnoreUnknownDefault"), there will  be  situations  where  an
{\ACE} interface function  needs  to  be  told  explicitly  to  ignore
options passed down recursively to it from calling functions. For this
purpose  we  have  provided  the  options   `aceignore'   (see~"option
aceignore") and `aceignoreunknown' (see~"option aceignoreunknown").

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Abbreviations and mixed case for ACE Options}

Except for limitations imposed by {\GAP}  e.g.\  clashes  with  {\GAP}
keywords and blank spaces not allowed in keywords, the options of  the
{\ACE} interface are the same as for the binary; so, for example,  the
options can appear in upper or lower case (or indeed, mixed case)  and
most may be abbreviated. Below we only list the options in  all  lower
case, and in their longest form; where  abbreviation  is  possible  we
give the shortest abbreviation in the  option's  description  e.g.~for
the `mendelsohn' option we state that  its  shortest  abbreviation  is
`mend', which means `mende', `mendel' etc.,  and  indeed,  `Mend'  and
`MeND', are all valid abbreviations of that option. Some options  have
synonyms e.g.~`cfactor' is an alternative for `ct'.

The complete list of {\ACE} options  known  to  the  {\ACE}  interface
functions, their abbreviations and the values that they are  known  to
take  may  be  gleaned  from   the   `KnownACEOptions'   record   (see
Section~"The KnownACEOptions Record").

Options  for each of  the       {\ACE}       interface       functions
`ACECosetTableFromGensAndRels',   `ACECosetTable',   `ACEStats'    and
`ACEStart' (see  Chapter~"Functions  for  Using  ACE  Interactively"),
comprise the few  non-{\ACE}-binary  options  (`silent',  `aceinfile',
`aceoutfile',   `aceignore',   `aceignoreunknown',    `acenowarnings',
`aceincomment',     `aceecho'     and     `echo')     discussed     in
Section "Non-ACE-binary  Options",  (almost)  all  single-word  {\ACE}
binary options and  `purer'  and  `purec'.  The  options  `purer'  and
`purec' give  the  {\ACE}  binary  options  `pure  r'  and  `pure  c',
respectively; (they are the only multiple-word {\ACE}  binary  options
that do not have a single word alternative).  The  *only*  single-word
{\ACE}  binary  options  that  are  *not*  available  via  the  {\ACE}
interface are abbreviations that clash with {\GAP} keywords (e.g.~`fi'
for `fill', `rec' for `recover' and  `continu'  for  `continue').  The
detail of this paragraph is  probably  of  little  importance  to  the
{\GAP} user; these comments have been included for the user who wishes
to reconcile the respective functionalities of  the  {\ACE}  interface
and  the  {\ACE}  standalone,  and  are  probably  of  most  value  to
standalone users.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Honouring of the order in which ACE Options are passed}

*Note:* Below we describe the intended behaviour,  but  unfortunately,
since {\GAP} 4.5  (approximately  when  {\ACE} 5.1  was  released) the
order of options  behind  the colon  is no longer honoured. Until this
is fixed, if the order of {\ACE} options needs to be respected,  users
should use {\ACE} interactively (see~"ACEStart").

It  is  important  to  realize  that  {\ACE}'s   options   (even   the
non-strategy options) are not orthogonal, i.e.\  the  order  in  which
they are put to {\ACE} can be important. For this reason, except for a
few options that have no effect on the course of an  enumeration,  the
order in which options are passed to the {\ACE} interface is preserved
when those same options are passed to the {\ACE} binary.  One  of  the
reasons for the non-orthogonality of options is to  protect  the  user
from obtaining invalid enumerations from bad combinations of  options;
another reason is that commonly one may specify a strategy option  and
override some of that strategy's defaults; the general  rule  is  that
the later option prevails. By the way, it's not illegal to select more
than one strategy, but it's not sensible; as just mentioned, the later
one prevails.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{What happens if no ACE Strategy Option or if no ACE Option is passed}

If  an  {\ACE}  interface  function   (`ACECosetTableFromGensAndRels',
`ACEStats',  `ACECosetTable'  or  `ACEStart')  is  given  no  strategy
option, the `default'  strategy  (see  Chapter~"Strategy  Options  for
ACE") is selected, and a number of options that {\ACE} needs to have a
value for are given default values, *prior* to the  execution  of  any
user options, if any. This ensures that {\ACE} has a value for all its
``run parameters'';  three  of  these  are  defined  from  the  {\ACE}
interface function arguments; and the remaining ``run parameters'', we
denote by ``{\ACE} Parameter Options''. For user convenience, we  have
provided the `ACEParameterOptions' record (see~"ACEParameterOptions"),
the fields of which are the ``{\ACE} Parameter Options''. The value of
each field (option) of the `ACEParameterOptions' record  is  either  a
default value or (in the case of an option that is set by a  strategy)
a record of default values that {\ACE} assumes when the user does  not
define a value for  the  option  (either  indirectly  by  selecting  a
strategy option or directly).

If the `default' strategy does not suffice, most usually a  user  will
select one of the other strategies  from  among  the  ones  listed  in
Chapter~"Strategy Options for ACE", and possibly modify  some  of  the
options by selecting from  the  options  in  this  chapter.  It's  not
illegal to select more than one strategy, but it's  not  sensible;  as
mentioned above, the later one prevails.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Interpretation of ACE Options}

Options may be given a value by an assignment to  the  name  (such  as
`time := <val>'); or be passed without assigning  a  value,  in  which
case {\GAP} treats the option as *boolean* and sets the option to  the
value `true', which  is  then  interpreted  by  the  {\ACE}  interface
functions. Technically speaking the {\ACE} binary itself does not have
boolean options, though it does have some options which  are  declared
by passing without a value  (e.g.  the  `hard'  strategy  option)  and
others that are boolean in the C-sense (taking on just the values 0 or
1).   The   behaviour    of    the    {\ACE}    interface    functions
(`ACECosetTableFromGensAndRels',   `ACEStats',   `ACECosetTable'    or
`ACEStart') is essentially  to  restore  as  much  as  is  possible  a
behaviour that mimics the {\ACE} standalone; a `false' value is always
translated to 0 and `true' may be translated to any of no-value, 0  or
1. Any option passed with an assigned value <val> other  than  `false'
or `true' is passed with the value <val> to the {\ACE}  binary.  Since
this may appear confusing, let's consider some examples.

\beginlist%unordered

\item{--} The `hard' strategy option  (see~"option  hard")  should  be
passed without a value, which in turn is passed to the  {\ACE}  binary
without  a  value.  However,  the  {\ACE}  interface  function  cannot
distinguish the option `hard' being passed without a  value,  from  it
being passed via `hard := true'. Passing `hard := false' or  `hard  :=
<val>' for any non-`true' <val> will however produce a warning message
(unless the option `acenowarnings' is passed) that the  value  0  (for
`false') or <val> is unknown for that  option.  Nevertheless,  despite
the warning, in this event, the {\ACE} interface function  passes  the
value to the {\ACE} binary. When the {\ACE} binary sees a line that it
doesn't understand it prints a warning  and  simply  ignores  it.  (So
passing `hard := false' will produce warnings, but will  have  no  ill
effects.) The reason we still pass  *unknown*  values  to  the  {\ACE}
binary is that it's conceivable a future version of the {\ACE}  binary
might have  several  `hard'  strategies,  in  which  case  the  {\ACE}
interface function will still complain (until it's made aware  of  the
new possible values) but it will perform in the correct  manner  if  a
value expected by the {\ACE} binary is passed.

\item{--} The `felsch' strategy option (see~"option  felsch")  may  be
passed without a value (which chooses the *felsch 0* strategy) or with
the values 0 or 1. Despite the fact that {\GAP} sees  this  option  as
*boolean*; it is *not*. There are two Felsch  strategies:  *felsch  0*
and *felsch 1*. To get the *felsch 1* strategy,  the  user  must  pass
`felsch := 1'. If the user were to pass `felsch := false'  the  result
would be the *felsch 0* strategy (since `false' is  always  translated
to 0), i.e.~the same as how `felsch := true' would be interpreted.  We
could protect the user more from  such  ideosyncrasies,  but  we  have
erred on the side of simplicity in order to make  the  interface  less
vulnerable to upgrades of the {\ACE} binary.

\endlist

The lesson from the two examples is: *check the documentation  for  an
option to see  how  it  will  be  interpreted*.  In  general,  options
documented (in this chapter) as *only* being no-value options  can  be
safely thought of as boolean (i.e.~you will get  what  you  expect  by
assigning `true' or  `false'),  whereas  strategy  (no-value)  options
should *not* be thought of as boolean (a `false' assignment will *not*
give you what you might have expected).

Options that are unknown to the {\ACE}  interface  functions  and  not
ignored (see below), that are passed without  a  value,  are  *always*
passed to the {\ACE} binary  as  no-value  options  (except  when  the
options are ignored); the user can over-ride this behaviour simply  by
assigning the intended value. Note that it is perfectly safe to  allow
the {\ACE} binary to be passed unknown options,  since  {\ACE}  simply
ignores options it doesn't understand, issues an error message  (which
is just a warning and is output by {\GAP} unless `acenowarnings'  (see
"option acenowarnings") is passed) and continues  on  with  any  other
options passed in exactly the way it would  have  if  the  ``unknown''
options had not been passed.

An option is  ignored  if  it  is  unknown  to  the  {\ACE}  interface
functions and one of the following is true:

\beginlist%unordered
\item{--} the global  variable  `ACEIgnoreUnknownDefault'  is  set  to
`false' (see~"ACEIgnoreUnknownDefault") or,

\item{--} the `aceignoreunknown' option (see~"option aceignoreunknown")
is passed, or 

\item{--} the `aceignore' option  is  passed  and  the  option  is  an
element of the list value of `aceignore' (see~"option aceignore").

\endlist

\index{debugging}
\indextt{ACEIgnoreUnknownDefault!use as debugging tool}
It    is    actually    *recommended*    that     the     user     set
`ACEIgnoreUnknownDefault' to `false', since this will allow  the  user
to see when  {\ACE}  functions  have  been  passed  options  that  are
``unknown'' to the {\ACE} package.  In  this  way  the  user  will  be
informed about misspelt options, for example. So it's a good debugging
tool. Also, if the {\ACE} binary is updated with a  version  with  new
options then these will not be known by the package (the {\GAP}  part)
and it will be necessary to set `ACEIgnoreUnknownDefault'  to  `false'
in order for the new options to be  passed  to  the  binary.  When  an
{\ACE} function is invoked indirectly by some function that was called
with non-{\ACE} options the warning messages may begin to be annoying,
and it's then a simple matter to set `ACEIgnoreUnknownDefault' back to
the {\ACE} 3.003 default value of `true'.

Warning messages regarding unknown  options  are  printed  unless  the
`acenowarnings' (see "option acenowarnings") is passed or  the  option
is ignored.

To see how options are interpreted by an  {\ACE}  interface  function,
pass the `echo' option.

As  mentioned  above,  any  option  that  the  {\ACE}  binary  doesn't
understand is simply ignored and a warning appears in the output  from
{\ACE}. If this occurs, you may wish to check the input fed to  {\ACE}
and the output from {\ACE}, which when {\ACE} is run non-interactively
are stored in files whose full path names are recorded in  the  record
fields   `ACEData.infile'   and    `ACEData.outfile',    respectively.
Alternatively, both interactively and non-interactively  one  can  set
the `InfoLevel' of `InfoACE' to 3 (see~"SetInfoACELevel"), to see  the
output from {\ACE}, or to 4 to  also  see  the  commands  directed  to
{\ACE}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{An Example of passing Options}

Continuing with the example of Section~"Using ACE Directly to Generate
a Coset Table", one could set the `echo' option to be  true,  use  the
`hard' strategy option, increase the workspace  to  $10^7$  words  and
turn messaging on (but to be fairly infrequent) by setting  `messages'
to a large positive value as follows:

\begintt
gap> ACECosetTable(fgens, rels, [c]
>                  : echo, hard, Wo := 10^7, mess := 10000);;
\endtt

As mentioned in the previous section, `echo' may be thought  of  as  a
boolean option, whereas `hard' is a strategy option (and hence  should
be thought of as a no-value option). Also, observe  that  two  options
have  been  abbreviated:  `Wo'  is  a  mixed  case   abbreviation   of
`workspace', and `mess' is an abbreviation of `messages'.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{The KnownACEOptions Record}

\>`KnownACEOptions' V

is a {\GAP} record whose fields are the {\ACE} options  known  to  the
{\ACE} interface; each field (known {\ACE} option) is  assigned  to  a
list of the form `[<i>, <ListOrFunction>]', where `<i>' is an  integer
representing the length of the shortest abbreviation of the option and
`<ListOrFunction>' is either a list of (known)  allowed  values  or  a
boolean function that may be used to determine if the given value is a
(known) valid value e.g.

\beginexample
gap> KnownACEOptions.compaction;
[ 3, [ 0 .. 100 ] ]

\endexample

indicates that the option `compaction' may be  abbreviated  to  `com'
and the (known) valid values are in the (integer) range 0 to 100; and

\beginexample
gap> KnownACEOptions.ct;
[ 2, <Category "IsInt"> ]

\endexample

indicates that there is essentially no abbreviation of `ct' (since its
shortest abbreviation is of length 2),  and a value of  `ct' is  known
to be valid if `IsInt' returns true for that value.

For user convenience, we provide the function

\>ACEOptionData( <optname> ) F

which for a string <optname> representing an {\ACE} option (or a guess
of one) returns a record with the following fields:

\beginitems

\quad`name'   & <optname> (unchanged);

\quad`known'  & `true' if <optname> is a valid mixed case abbreviation
of a known {\ACE} option, and false otherwise;

\quad`fullname'& the lower case unabbreviated form of <optname> if the
`known'  field  is  set  `true',  or  <optname>  in  all  lower  case,
otherwise;

\quad`synonyms'& a  list  of  known  {\ACE}  options  synonymous  with
<optname>, in lowercase unabbreviated form, if the  `known'  field  is
set `true', or a list containing just <optname>  in  all  lower  case,
otherwise;

\quad`abbrev' & the shortest lowercase abbreviation  of  <optname>  if
the `known' field is set `true',  or  <optname>  in  all  lower  case,
otherwise.

\enditems

For more on synonyms of {\ACE} options, see~"ACEOptionSynonyms".

The function `ACEOptionData' provides the  user  with  all  the  query
facility she should ever need; nevertheless, we provide the  following
functions.

\>IsKnownACEOption( <optname> ) F

returns `true' if <optname> is a mixed case abbreviation of a field of
`KnownACEOptions',           or           `false'           otherwise.
`IsKnownACEOption(<optname>);' is equivalent to

\)\kernttindent{ACEOptionData(<optname>).known;}

\>ACEPreferredOptionName( <optname> ) F

returns the lowercase unabbreviated first alternative of <optname>  if
it is a known {\ACE} option, or  <optname>  in  lowercase,  otherwise.
`ACEPreferredOptionName(<optname>);' is equivalent to

\)\kernttindent{ACEOptionData(<optname>).synonyms[1];}

\>IsACEParameterOption( <optname> ) F

returns true if <optname> is an ``{\ACE} parameter  option''.  ({\ACE}
Parameter Options  are  described  in  Section~"ACEParameterOptions").
`IsACEParameterOption(<optname>);' is equivalent to

\)\kernttindent{ACEPreferredOptionName(<optname>) in RecNames(ACEParameterOptions);}

\>IsACEStrategyOption( <optname> ) F

returns true if <optname> is  an  ``{\ACE}  strategy  option''  (see
Section~"The                ACEStrategyOptions                 list").
`IsACEStrategyOption(<optname>);' is equivalent to

\)\kernttindent{ACEPreferredOptionName(<optname>) in ACEStrategyOptions;}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{The ACEStrategyOptions List}

\>`ACEStrategyOptions' V

is a {\GAP} list that contains  the  strategy  options  known  to  the
{\ACE} interface functions:

\beginexample
gap> ACEStrategyOptions;
[ "default", "easy", "felsch", "hard", "hlt", "purec", "purer", "sims" ]

\endexample

See Chapter~"Strategy Options  for  ACE"  for  details  regarding  the
{\ACE} strategy options.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{ACE Option Synonyms}\nolabel

\>`ACEOptionSynonyms' V

is a {\GAP} record. A number of known {\ACE}  options  have  synonyms.
The fields of the `ACEOptionSynonyms'  record  are  the  ``preferred''
option names and the values assigned to the fields are  the  lists  of
synonyms  of  those  option  names.  What   makes   an   option   name
``preferred'' is somewhat arbitrary (in most cases, it is  simply  the
shortest of a list of  synonyms).  For  a  ``preferred''  option  name
<optname> that has synonyms, the complete  list  of  synonyms  may  be
obtained     by     concatenating     `[     <optname>     ]'      and
`ACEOptionSynonyms.(<optname>)', e.g.

\beginexample
gap> Concatenation( [ "messages" ], ACEOptionSynonyms.("messages") );
[ "messages", "monitor" ]

\endexample

More generally, for an arbitrary option name  <optname>  its  list  of
synonyms (which may be a list of one element) may be obtained  as  the
`synonyms' field of the record returned by  `ACEOptionData(<optname>)'
(see~"ACEOptionData").

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Non-ACE-binary Options}

\>`NonACEbinOptions' V

is a {\GAP} list of options that have  meaning  only  for  the  {\ACE}
Package interface, i.e.~options in `KnownACEOptions'  that  are  *not*
{\ACE} binary options; each such option is described in detail  below.
*Except* for  the  options  listed  in  `NonACEbinOptions'  and  those
options that are excluded via the `aceignore'  and  `aceignoreunknown'
options  (described  below),   *all*   options   that   are   on   the
`OptionsStack' when an {\ACE} interface function is called, are passed
to the {\ACE} binary. Even options that produce the  warning  message:
```unknown (maybe new) or bad''', by virtue of not being  a  field  of
`KnownACEOptions', are passed to the {\ACE} binary  (except  that  the
options `purer' and `purec' are first translated to `pure r' and `pure
c', respectively). When the {\ACE} binary encounters an option that it
doesn't understand it issues a  warning  and  simply  ignores  it;  so
options accidentally passed to {\ACE} are unlikely to pose problems.

We also mention here, since  it  is  related  to  an  option  of  this
section, the following.

\>`ACEIgnoreUnknownDefault' V

is a global variable (*not* an option) that is initially  set  by  the
{\ACE} package to `true', and is the default action that {\ACE}  takes
for options that are unknown to the {\ACE} package  (but  may  be  new
options provided in a new version of the {\ACE} binary).  Despite  the
fact that it is normally set `true', it is recommended (especially for
the novice user of the {\ACE} package) to set `ACEIgnoreUnknownDefault
:= false'; the worst that can happen is being annoyed by  a  profusion
of warnings of unknown options. For individual functions, the user may
use the option `aceignoreunknown' (see~"option  aceignoreunknown")  to
over-ride the setting of `ACEIgnoreUnknownDefault'.

Here now, are the  few  options  that  are  available  to  the  {\GAP}
interface to {\ACE} that have no counterpart in the {\ACE} standalone:

\beginitems

\>`silent'{option silent}@{option `silent'}& 
Inhibits an `Error' return when generating a coset table.

If a coset  enumeration  that  invokes  `ACECosetTableFromGensAndRels'
does not finish within the preset limits, an error is  raised  by  the
interface to  {\GAP},  unless  the  option  `silent'  or  `incomplete'
(see~"option incomplete") has been set; in the former case, `fail'  is
returned.  This  option  is  included  to  make   the   behaviour   of
`ACECosetTableFromGensAndRels' compatible with that  of  the  function
`CosetTableFromGensAndRels' it replaces. If the option `incomplete' is
also set, it overrides option `silent'.

\>`lenlex'{option lenlex}@{option `lenlex'}& 
Ensures that `ACECosetTable' and `ACECosetTableFromGensAndRels' output
a coset table that is `lenlex' standardised.

The  `lenlex'  scheme,  numbers  cosets  in  such  a  way  that  their
``preferred'' (coset) representatives, in an  alphabet  consisting  of
the user-submitted generators and their inverses,  are  ordered  first
according to `length' and then according to a `lexical'  ordering.  In
order to describe what the `lenlex' scheme's  `lexical'  ordering  is,
let us consider an example. Suppose the generators  submitted  by  the
user are, in user-supplied order, `[x, y, a, b]',  and  represent  the
inverses of these generators by the corresponding  uppercase  letters:
`[X, Y, A, B]', then  the  `lexical'  ordering  of  `lenlex'  is  that
derived from defining `x \< X \< y \< Y \< a \< A \< b \< B'.

*Notes:*
In  some  circumstances,  {\ACE}  prefers  to  swap  the   first   two
generators;   such   cases    are    detected    by    the    function
`IsACEGeneratorsInPreferredOrder'                                 (see
"IsACEGeneratorsInPreferredOrder"). In such cases, special  action  is
taken to avoid {\ACE} swapping the first two generators;  this  action
is   described   in   the   notes   for    `ACEStandardCosetNumbering'
(see~"ACEStandardCosetNumbering").  When  this   special   action   is
invoked, a side-effect is that any setting of the `asis'  (see~"option
asis") option by the user is ignored.

The  `lenlex'  standardisation  scheme  is  the  default  coset  table
standardisation  scheme  of  {\GAP}  (since  version  4.3).   However,
`semilenlex' was the standardisation scheme for versions of {\GAP}  up
to {\GAP}~4.2. Both schemes are described in detail in  Section~"Coset
Table Standardisation Schemes".

\>`semilenlex'{option semilenlex}@{option `semilenlex'}& 
Ensures that `ACECosetTable' and `ACECosetTableFromGensAndRels' output
a coset table that is `semilenlex' standardised.

The `semilenlex' scheme, numbers cosets  in  such  a  way  that  their
``preferred'' (coset) representatives, in an  alphabet  consisting  of
only the user-submitted generators, are  ordered  first  according  to
`length' and then according to a `lexical' ordering.

*Note:*
Up to {\GAP}~4.2, `semilenlex' was the default standardisation  scheme
used by {\GAP} (see also~"option lenlex").

\>`incomplete'{option incomplete}@{option `incomplete'}& 
Allows the return  of  an  `incomplete'  coset  table,  when  a  coset
enumeration does not finish within preset limits.

If a coset enumeration that invokes `ACECosetTableFromGensAndRels'  or
`ACECosetTable' does not finish within the preset limits, an error  is
raised  by  the  interface  to  {\GAP},  unless  the  option  `silent'
(see~"option silent") or `incomplete' has  been  set;  in  the  latter
case, a partial coset table, that is a valid {\GAP} list of lists,  is
returned. Each position of the table  without  a  valid  coset  number
entry is filled with a zero. If  the  option  `silent'  is  also  set,
`incomplete'  prevails.  Since  {\GAP}~4.3,  an  incomplete  table  is
returned reduced (i.e.~with  insignificant  coset  numbers  ---  those
appearing only in their place of definition --- removed) and  `lenlex'
standardised (regardless of whether  the  `semilenlex'  option  is  in
force). (For GAP~4.2, an incomplete table was returned  unstandardised
unless the `lenlex' option (see~"option lenlex") was also set, and the
table was also not reduced.) When an incomplete table is  returned,  a
warning is emitted at `InfoACE' or `InfoWarning' level 1.

\>`aceinfile:=<filename>'{option aceinfile}@{option `aceinfile'}&
Creates an {\ACE} input file <filename> for use  with  the  standalone
only; <filename> should be a string. (Shortest abbreviation: `acein'.)

This option is only relevant to `ACECosetTableFromGensAndRels' and  is
ignored if included as an option for  invocations  of  `ACEStats'  and
`ACEStart'. If this option is used, {\GAP} creates an input file  with
filename <filename> only, and then exits (i.e.~the  {\ACE}  binary  is
not called). This option is  provided  for  users  who  wish  to  work
directly with the {\ACE} standalone. The full path to the  input  file
normally used by {\ACE} (i.e.~when option `aceinfile' is not used)  is
stored in `ACEData.infile'.


\>`aceoutfile:=<filename>'{option aceoutfile}@{option `aceoutfile'}&
Redirects {\ACE} output to file <filename>;  <filename>  should  be  a
string. (Shortest abbreviation: `aceo'.)

This  is  actually  a  synonym  for  the  `ao'  option.  Please  refer
to~"option ao", for further discussion of this option.

\>`aceignore:=<optionList>'{option aceignore}@{option `aceignore'}&
Directs an {\ACE} function to  ignore  the  options  in  <optionList>;
<optionList> should be a list of strings.
(Shortest abbreviation: `aceig'.)

If a function called with its own options, in  turn  calls  an  {\ACE}
function for which those options are not intended, the {\ACE} function
will pass those options to the {\ACE} binary.  If  those  options  are
unknown to  the  {\ACE}  interface  (and  `ACEIgnoreUnknownDefault  :=
false'      and      `aceignoreunknown'      is      not       passed;
see~"ACEIgnoreUnknownDefault" and~"option aceignoreunknown") a warning
is issued. Options that are unknown to the {\ACE}  binary  are  simply
ignored by {\ACE} (and a warning that the option was  ignored  appears
in the  {\ACE}  output,  which  the  user  will  not  see  unless  the
`InfoLevel' of `InfoACE' or `InfoWarning' is set to  1).  This  option
enables the user to avoid such  options  being  passed  at  all,  thus
avoiding the warning messages and also any options that coincidentally
are {\ACE} options but are not intended for the {\ACE} function  being
called.

\>`aceignoreunknown'{option aceignoreunknown}@{option `aceignoreunknown'}&
Directs an {\ACE} function to ignore any  options  not  known  to  the
{\ACE} interface.
(Shortest abbreviation: `aceignoreu'.)

This option is provided for similar reasons to `aceignore'.  Normally,
it is safe to include it, to avoid aberrant warning messages from  the
{\ACE} interface. However, fairly obviously, it should not  be  passed
without a value (or set to `true') in the situation where a new {\ACE}
binary has been installed with new options that are not  listed  among
the fields of `KnownACEOptions', which you intend to use. Omitting the
`aceignoreunknown' option is equivalent to setting it to the value  of
`ACEIgnoreUnknownDefault' (see "ACEIgnoreUnknownDefault"); i.e.~it  is
superfluous    if    `ACEIgnoreUnknownDefault    :=    true'    unless
`aceignoreunknown' is set to `false'.

\>`acenowarnings'{option acenowarnings}@{option `acenowarnings'}& 
Inhibits the warning message ```unknown (maybe new) or bad option'''
for options not listed in `KnownACEOptions'.
(Shortest abbreviation: `acenow'.)

This option suppresses the warning messages for  unknown  options  (to
the {\ACE} interface), but unlike `aceignore'  and  `aceignoreunknown'
still allows them to be passed to the {\ACE} binary.

\>`echo'{option echo}@{option `echo'} 
\>`echo:=2'{option echo}@{option `echo'}& 
Echoes arguments and options (and indicates how options were handled).

Unlike the previous options of this  section,  there  *is*  an  {\ACE}
binary option `echo'. However, the `echo' option  is  handled  by  the
{\ACE} interface and is not passed to the {\ACE} binary. (If you  wish
to put  `echo'  in  a  standalone  script  use  the  `aceecho'  option
following.) If `echo' is passed with the value 2 then a  list  of  the
options (together with their values) that are set via {\ACE}  defaults
are also echoed to the screen.

\>`aceecho'{option aceecho}@{option `aceecho'}& 
The {\ACE} binary's `echo' command.

This option is only included so  that  a  user  *can*  put  an  `echo'
statement in  an  {\ACE}  standalone  script.  Otherwise,  use  `echo'
(above).

\>`aceincomment:=<string>'{option aceincomment}@{option `aceincomment'}&
Print 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.

\>`aceexampleoptions'{option aceexampleoptions}@{option `aceexampleoptions'}&
An *internal* option for `ACEExample'.

This option is passed  *internally*  by  `ACEExample'  to  the  {\ACE}
interface function  it  calls,  when  one  invokes  `ACEExample'  with
options. Its purpose is to provide a mechanism for the over-riding  of
an example's options by the user. The option name is deliberately long
and has no abbreviation to discourage user use.

\enditems

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{ACE Parameter Options}\nolabel

\>`ACEParameterOptions' V

is a {\GAP} record, whose fields are the ``{\ACE} Parameter Options''.
The ``{\ACE} Parameter Options'' are options which, if not supplied  a
value by the user, are supplied a default value by  {\ACE}.  In  fact,
the ``{\ACE} Parameter Options'' are those options that appear  (along
with `Group Generators', `Group Relators' and  `Subgroup  Generators',
which are defined from {\ACE} interface  function  arguments)  in  the
``Run Parameters'' block of {\ACE}  output,  when,  for  example,  the
`messages' option is non-zero.

For each field ({\ACE} parameter option) of the  `ACEParameterOptions'
record, the value assigned is  the  default  value  (or  a  record  of
default values) that are supplied by {\ACE} when  the  option  is  not
given a value by the user (either indirectly by selecting  a  strategy
option or directly).

In the cases where the value of a field of  the  `ACEParameterOptions'
record is itself a record, the fields of that record are `default' and
strategies for which the value assigned by that strategy differs  from
the `default' strategy. A ``strategy'', here, is the  strategy  option
itself, if it is only  a  no-value  option,  or  the  strategy  option
concatenated with any of its integer values  (as  strings),  otherwise
(e.g.~`felsch0' and `sims9'  are  strategies,  and  `hlt'  is  both  a
strategy and a strategy option). As an exercise, the reader might like
to try to reproduce the table at the  beginning  of  Chapter~"Strategy
Options for ACE" using the `ACEParameterOptions'  record.  (Hint:  you
first need to select those fields of the `ACEParameterOptions'  record
whose values are records with at least two fields.)

*Note:*
Where  an  ``{\ACE}  Parameter  Option''  has   synonyms,   only   the
``preferred'' option name (see~"ACEOptionSynonyms") appears as a field
of `ACEParameterOptions'. The  complete  list  of  ``{\ACE}  Parameter
Options'' may be obtained by

\beginexample
gap> Concatenation( List(RecNames(ACEParameterOptions),
>                        optname -> ACEOptionData(optname).synonyms) );
[ "path", "subgroup", "max", "time", "fill", "ffactor", "asis", "ct", 
  "cfactor", "compaction", "dmode", "dsize", "enumeration", "hole", 
  "lookahead", "loop", "mendelsohn", "messages", "monitor", "no", "pmode", 
  "psize", "rt", "rfactor", "row", "workspace" ]

\endexample

We describe the ``{\ACE} Parameter Options'' in the  Sections~"General
ACE Parameter Options  that  Modify  the  Enumeration  Process",  "ACE
Parameter Options  Modifying  C  Style  Definitions",  "ACE  Parameter
Options for R Style Definitions", "ACE Parameter Options for Deduction
Handling", "Technical ACE Parameter Options", "ACE  Parameter  Options
controlling ACE Output", and~"ACE Parameter Options that give Names to
the Group and Subgroup", following.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{General ACE Parameter Options that Modify the Enumeration Process}

\beginitems

\>`asis'{option asis}@{option `asis'}&
Do not reduce relators. (Shortest abbreviation: `as'.)

By default, {\ACE} freely  and cyclically reduces the relators, freely
reduces  the  subgroup generators,  and  sorts  relators and  subgroup
generators in length-increasing  order.  If you do not  want this, you
can switch it off by setting the `asis' option.

*Notes:* As well as allowing you  to use the presentation *as* it *is*
given,  this  is  useful for  forcing  definitions  to  be made  in  a
prespecified  order,  by  introducing  dummy  (i.e.,  freely  trivial)
subgroup generators.   (Note that the  exact form of  the presentation
can  have a significant  impact on  the enumeration  statistics.)  For
some fine points of the influence of `asis' being set on the treatment
of involutory generators see the {\ACE} standalone manual.

\>`ct:=<val>'{option ct}@{option `ct'}
\>`cfactor:=<val>'{option cfactor}@{option `cfactor'}&
Number of C style definitions per pass; `<val>' should be an  integer. 
(Shortest abbreviation of `cfactor' is `c'.)

The absolute value of `<val>' sets the number of C  style  definitions
per pass through the enumerator's main loop. The sign of `<val>'  sets
the style. The possible combinations of the values of  `ct'  and  `rt'
(described below) are given in the  table  of  enumeration  styles  in
Section~"Enumeration Style".

\>`rt:=<val>'{option rt}@{option `rt'}
\>`rfactor:=<val>'{option rfactor}@{option `rfactor'}&
Number of R style definitions per pass; `<val>' should be an  integer. 
(Shortest abbreviation of `rfactor' is `r'.)

The absolute value of `<val>' sets the number of R  style  definitions
per pass through the enumerator's main loop. The sign of `<val>'  sets
the style. The possible combinations of the values of `ct'  (described
above) and `rt' are given  in  the  table  of  enumeration  styles  in
Section~"Enumeration Style".

\>`no:=<val>'{option no}@{option `no'}&
The number of group relators to include in the subgroup;  
`<val>' should be an integer greater than or equal to $-1$.

It is sometimes helpful to include the group relators into the list of
the subgroup generators, in the sense that they are applied  to  coset
number 1 at the start of an enumeration. A value of 0 for this  option
turns this feature off and the (default) argument of $-1$ includes all
the relators. A positive argument includes  the  specified  number  of
relators,  in  order.  The  `no'  option  affects  only  the   C style
procedures.

\>`mendelsohn'{option mendelsohn}@{option `mendelsohn'}&
Turns on mendelsohn processing. (Shortest abbreviation: `mend'.)

Mendelsohn style processing during relator scanning/closing is  turned
on by giving this option. Off is the default, and  here  relators  are
scanned only from the start (and end) of a relator. Mendelsohn  ``on''
means that all  (different)  cyclic  permutations  of  a  relator  are
scanned.

The effect of Mendelsohn style processing  is  case-specific.  It  can
mean the difference between success or failure, or it can  impact  the
number of coset numbers required, or it  can  have  no  effect  on  an
enumeration's statistics.

*Note:* Processing all cyclic permutations of the relators can be very
time-consuming,  especially if  the  presentation is  large.  So,  all
other things being equal, the  Mendelsohn flag should normally be left
off.

\enditems

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{ACE Parameter Options Modifying C Style Definitions}

\atindex{C style}{@C style!definition}
The  next  three  options  are  relevant  only  for  making  *C  style
definitions* (see Section~"Enumeration Style"). Making definitions  in
C style, that is filling the coset table line by line, it can be  very
advantageous to  switch  to  making  definitions  from  the  preferred
definition stack. Possible definitions  can  be  extracted  from  this
stack in  various  ways  and  the  two  options  `pmode'  and  `psize'
(see~"option pmode" and~"option psize"  respectively)  regulate  this.
However it should be clearly understood that  making  all  definitions
from a preferred definition stack one may  violate  the  condition  of
Mendelsohn's theorem, and the option `fill' (see~"option fill") can be
used to avoid this.

\beginitems

\>`fill:=<val>'{option fill}@{option `fill'}
\>`ffactor:=<val>'{option ffactor}@{option `ffactor'}&
Controls the preferred definition strategy by setting the fill factor;
`<val>' must be a non-negative integer.
(Shortest abbreviation of `fill' is `fil', and  shortest  abbreviation
of `ffactor' is `f'.)

Unless prevented by the fill factor, gaps of length one  found  during
deduction  testing  are  preferentially   filled   (see \cite{Hav91}).
However, this potentially violates the  formal  requirement  that  all
rows in the coset table are eventually filled (and tested against  the
relators). The fill factor  is  used  to  ensure  that  some  constant
proportion of the coset table is always kept filled. Before defining a
coset number to fill a  gap  of  length  one,  the  enumerator  checks
whether `fill' times the completed part of the table is at  least  the
total size of the table  and,  if  not,  fills  coset  table  rows  in
standard order (i.e.~C style; see Section~"Enumeration Style") instead
of filling gaps.

An  argument of  0  selects  the default  value  of $\lfloor  5(n+2)/4
\rfloor$,  where $n$  is the  number of  columns in  the  table.  This
default  fill factor  allows  a moderate  amount  of gap-filling.   If
`fill' is  1, then there is  no gap-filling.  A large  value of `fill'
can cause  what is in effect  infinite looping (resolved  by the coset
enumeration failing).   However, in general,  a large value  does work
well.  The  effects of the various gap-filling  strategies vary widely.
It is  not clear  which values are  good general defaults  or, indeed,
whether any strategy is always ``not too bad''.

This option is identified as `Fi'  in  the  ``Run  Parameters''  block
(obtained when `messages' is non-zero) of the {\ACE} output, since for
the {\ACE} binary, `fi' is an allowed abbreviation of `fill'. However,
`fi' is a {\GAP} keyword and so the shortest  abbreviation  of  `fill'
allowed by the interface functions is `fil'.

\>`pmode:=<val>'{option pmode}@{option `pmode'}&
Option for preferred definitions; `<val>' should  be  in  the  integer
range 0 to 3. (Shortest abbreviation: `pmod'.)

The  value of  the  `pmode' option  determines  which definitions  are
preferred.  If  the argument is  0, then Felsch style  definitions are
made using  the next empty table  slot.  If the  argument is non-zero,
then gaps of length one found during relator scans in Felsch style are
preferentially  filled  (subject to  the  value  of  `fill').  If  the
argument  is 1,  they are  filled  immediately, and  if it  is 2,  the
consequent deduction  is also made  immediately (of course,  these are
also put on the deduction stack).  If the argument is 3, then the gaps
of length one are noted in the preferred definition queue.

Provided such a gap survives (and no coincidence occurs, which  causes
the queue to be discarded) the next coset number will  be  defined  to
fill the oldest gap of length one. The default value is either 0 or 3,
depending on the strategy selected (see Chapter~"Strategy Options  for
ACE"). If you want to know more details, read the code.


\>`psize:=<val>'{option psize}@{option `psize'}&
Size of preferred definition queue; `<val>' *must* be 0 or $2^n$,  for
some integer $n>0$. (Shortest abbreviation: `psiz'.)

The  preferred definition  queue is  implemented as  a  ring, dropping
earliest entries. An argument of 0 selects  the default size of $256$.
Each  queue slot takes two words (i.e., 8 bytes),  and the  queue  can
store up to $2^n-1$ entries.

\enditems

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{ACE Parameter Options for R Style Definitions}

\atindex{R style}{@R style!definition}
\beginitems

\>`row:=<val>'{option row}@{option `row'}&
Set the ``row filling'' option; `<val>' is either 0 or 1.

By default, ``row filling'' is on (i.e.~`true' or 1). To turn  it  off
set `row' to `false' or 0 (both are translated to 0 when passed to the
{\ACE}  binary).  When   making   HLT   style   (i.e.~R   style;   see
Section~"Enumeration Style") definitions, rows of the coset table  are
scanned for holes after its coset  number  has  been  applied  to  all
relators, and definitions are made to fill any holes encountered. This
will,  in  particular,  guarantee  fulfilment  of  the  condition   of
Mendelsohn's  Theorem.  Failure  to  do  so  can  cause  even   simple
enumerations to overflow.

\>`lookahead:=<val>'{option lookahead}@{option `lookahead'}&
Lookahead; `<val>' should be in the integer range 0 to 4.
(Shortest abbreviation: `look'.)
  
Although HLT style strategies are fast, they are local, in  the  sense
that  the  implications  of  any  definitions/deductions  made   while
applying coset numbers may not become apparent until much  later.  One
way to alleviate this problem is to perform  lookaheads  occasionally;
that is, to test the information in the table, looking for  deductions
or  concidences.  {\ACE}  can  perform  a  lookahead  when  the  table
overflows, before the compaction routine is called. Lookahead  can  be
done using the entire table or only that part of the table  above  the
current coset number, and it  can  be  done  R style  (scanning  coset
numbers from the  beginning  of  relators)  or  C style  (testing  all
definitions in all essentially different positions).

The following are the effects of the possible values of `lookahead':

\beginlist%unordered

\item{--} 0 disables lookahead;
\item{--} 1 does a partial table lookahead, R style; 
\item{--} 2 does a whole table lookahead, C style; 
\item{--} 3 does a whole table lookahead, R style; and
\item{--} 4 does a partial table lookahead, C style.  

\endlist

The default is 1 if the `hlt' strategy is used and  0  otherwise;  see
Chapter~"Strategy Options for ACE".

Section~"Enumeration Style" describes the various enumeration  styles,
and, in particular, R style and C style.

\enditems

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{ACE Parameter Options for Deduction Handling}

\beginitems

\>`dmode:=<val>'{option dmode}@{option `dmode'}&
Deduction mode; `<val>' should be in the integer range 0 to 4.
(Shortest abbreviation: `dmod'.)

A completed table  is only valid if every table  entry has been tested
in all essentially different  positions in all relators.  This testing
can either be done directly (`felsch' strategy;  see~"option  felsch")
or via relator scanning (`hlt' strategy; see~"option hlt"). If  it  is
done directly, then more than one deduction (i.e., table entry) can be
waiting to be processed at any one time. So  the  untested  deductions
are stored in a stack. Normally this stack is fairly small but, during
a collapse, it can become very large.

This command allows the user  to  specify  how  deductions  should  be
handled. The value <val> has the following interpretations:

\beginlist%unordered

\item{--} $0$:  
discard deductions if there is no stack space left;

\item{--} $1$: 
as for $0$, but purge any redundant coset numbers on the  top  of  the
stack at every coincidence;

\item{--} $2$: 
as for 0, but purge all redundant coset  numbers  from  the  stack  at
every coincidence;

\item{--} $3$:
discard the entire stack if it overflows; and

\item{--} $4$:
if the stack overflows, double the stack size and purge all  redundant
coset numbers from the stack.

\endlist

The default deduction mode is either $0$  or  $4$,  depending  on  the
strategy selected (see Chapter~"Strategy Options for ACE"), and it  is
recommended that you stay with the default. If you want to  know  more
details, read the well-commented C code.

*Notes:*
If deductions are discarded for any reason, then a final relator check
phase  will be run  automatically at  the end  of the  enumeration, if
necessary, to check the result.

\>`dsize:=<val>'{option dsize}@{option `dsize'}&
Deduction stack size; `<val>' should be a non-negative integer.
(Shortest abbreviation: `dsiz'.)

Sets the  size of  the (initial) allocation  for the  deduction stack.
The size is  in terms of the number of  deductions, with one deduction
taking two words (i.e., 8 bytes).  The default size, of $1000$, can be
selected  by  a value  of  0.   See the  `dmode' entry  for a  (brief)
discussion of deduction handling.

\enditems

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Technical ACE Parameter Options}

The following options do not affect how the coset enumeration is done,
but how it  uses the computer's resources. They  might thus affect the
runtime as  well as  the range of  problems that  can be tackled  on a
given machine.

\beginitems

\>`workspace:=<val>'{option workspace}@{option `workspace'}&
Workspace size in words (default $10^6$);
`<val>' should be an expression that evaluates to a positive  integer,
or a string of digits ending in a  `k',  `M'  or  `G'  representing  a
multiplication  factor  of  $10^3$,  $10^6$  or  $10^9$,  respectively
e.g.~both `workspace := 2 * 10^6' and `workspace :=  "2M"'  specify  a
workspace  of  $2\times10^6$  words.  Actually,  if   the   value   of
`workspace' is entered as a string, each of `k', `M' or  `G'  will  be
accepted in either upper or lower case. (Shortest abbreviation: `wo'.)

By default, {\ACE} has a physical table size of $10^6$ words (i.e., $4
\times 10^6$ bytes in the  default 32-bit environment).  The number of
coset numbers in the table is  the table size divided by the number of
columns.   Although  the  number   of  coset  numbers  is  limited  to
$2^{31}-1$ (if the C `int' type is 32 bits), the table size can exceed
the $4$GByte 32-bit limit if a suitable machine is used.

\>`time:=<val>'{option time}@{option `time'}&
Maximum execution time in seconds; `<val>' must be an integer  greater
than or equal to $-1$. (Shortest abbreviation: `ti'.)

The `time' command  puts a time limit (in seconds) on  the length of a
run. The default is $-1$  which is no  time limit. If the  argument is
$\ge0$ then the total elapsed time for this call is checked at the end
of each pass through the enumerator's main loop, and if it's more than
the limit the run is stopped and the current table returned.

Note that a limit of $0$ performs exactly one pass  through  the  main
loop, since $0 \ge 0$.

The time  limit is approximate, in  the sense that  the enumerator may
run for a longer, but never a shorter, time.  So, if there is, e.g., a
big collapse (so that the time round the loop becomes very long), then
the run may run over the limit by a large amount.

*Notes:*
The time limit is CPU-time, not wall-time.  As  in  all  timing  under
UNIX, the clock's granularity  (usually  $10$  milliseconds)  and  the
system load can  affect  the  timing;  so  the  number  of  main  loop
iterations in a given time may vary.

\>`loop:=<val>'{option loop}@{option `loop'}&
Loop limit; `<val>' should be a non-negative integer.

The core enumerator is organised as a state machine,  with  each  step
performing an ``action'' (i.e., lookahead, compaction) or a  block  of
actions (i.e.,  $|`ct'|$  coset  number  definitions,  $|`rt'|$  coset
number applications). The number  of  passes  through  the  main  loop
(i.e., steps) is counted, and the enumerator can make an early  return
when this count hits the value of `loop'. A value of $0$, the default,
turns this feature off.

*Guru Notes:*
You can do lots of really neat things using this feature, but you need
some understanding of the internals of {\ACE} to get real benefit from
it.

\>`path'{option path}@{option `path'}&
Turns on path compression.

To correctly  process  multiple  concidences,  a  union-find  must  be
performed. If both path compression and weighted union are used,  then
this can be done in essentially linear time (see, e.g., \cite{CLR90}).
Weighted union alone, in the worst-case, is worse than linear, but  is
subquadratic. In practice, path compression  is  expensive,  since  it
involves many coset table accesses. So, by default,  path  compression
is turned off; it can be turned on by `path'. It has no effect on  the
result, but may affect the running time and the internal statistics.

*Guru Notes:*
The whole question of the best way to handle large coincidence forests
is problematic.  Formally, {\ACE} does  not do a weighted union, since
it is constrained to replace the higher-numbered of a coincident pair.
In practice,  this seems  to amount to  much the same  thing!  Turning
path  compression on  cuts down  the  amount of  data movement  during
coincidence processing at the expense of having to trace the paths and
compress them.  In general, it does not seem to be worthwhile.

\index{dead coset (number)}
\>`compaction:=<val>'{option compaction}@{option `compaction'}&
Percentage of dead coset numbers to trigger compaction; 
`<val>' should be an integer (percentage) in the integer  range  0  to
100. (Shortest abbreviation: `com'.)

\index{dead coset (number)}
The option `compaction' sets the percentage of  *dead*  coset  numbers
needed  to  trigger  compaction  of  the  coset   table,   during   an
enumeration. A *dead* coset (number) is a coset  number  found  to  be
coincident with a smaller coset number. The  default  is  10  or  100,
depending on the strategy  used  (see  Chapter~"Strategy  Options  for
ACE").

Compaction recovers the space allocated to  coset  numbers  which  are
flagged as dead. It results in a table  where  all  the  active  coset
numbers are numbered contiguously from 1, and with  the  remainder  of
the table available for new coset numbers.

The coset table is compacted when a definition of a  coset  number  is
required, there is no space for a  new  coset  number  available,  and
provided that the given percentage of the coset  table  contains  dead
coset numbers. For example, if `compaction'  =  $20$  then  compaction
will occur only if 20\% or more of the coset numbers in the table  are
dead. An argument of 100 means that  compaction  is  never  performed,
while an argument of 0 means always compact, no matter  how  few  dead
coset numbers there are (provided there is at least one, of course).

Compaction may be performed  multiple times during an enumeration, and
the table that results from an  enumeration may or may not be compact,
depending on whether or not there have been any coincidences since the
last compaction (or  from the start of the  enumeration, if there have
been no compactions).

*Notes:*
In some strategies (e.g., `hlt'; see~"option hlt") a  lookahead  phase
may be run before compaction is attempted. In other strategies  (e.g.,
`sims := 3'; see~"option sims")  compaction  may  be  performed  while
there are  outstanding  deductions;  since  deductions  are  discarded
during compaction, a final lookahead  phase  will  (automatically)  be
performed.

\index{dead coset (number)}
Compacting a table ``destroys'' information and history, in the  sense
that the coincidence list is deleted, and the table  entries  for  any
dead coset numbers are deleted.

\>`max:=<val>'{option max}@{option `max'}&
Sets the maximum coset number that can be defined;
`<val>' should be $0$ or an integer greater than or equal to 2.

By default (which is the case `max'${}=0$), all of  the  workspace  is
used, if necessary, in building the coset table. So the table size (in
terms of the number of rows) is an  upper  bound  on  how  many  coset
numbers can be alive at any one time. The `max' option allows a  limit
to be placed on how much physical table space is made available to the
enumerator. Enough space for at least two  coset  numbers  (i.e.,  the
subgroup and one other) must be made available.

*Notes:*
If the `easy'  strategy  (see~"option  easy")  is  selected,  so  that
`compaction' (see~"option compaction") is off (i.e.~set  to  100)  and
`lookahead' (see~"option lookahead") is off (i.e.~set to 0), and `max'
is set to a positive integer, then coset numbers are not  reused,  and
hence `max' bounds the *total* number `totcosets' (see  Section~"Coset
Statistics  Terminology")  of  coset   numbers   defined   during   an
enumeration.

On the other hand, if one (or both) of `compaction' or `lookahead'  is
not off, then some reuse of coset numbers may occur, so that, for  the
case where `max' is a positive integer, the value of  `totcosets'  may
be greater than `max'.

However,  whenever  `max'  is  set  to  a   positive   integer,   both
*activecosets* (the number of *alive* coset numbers at the end  of  an
enumeration) and  *maxcosets*  (the  maximum  number  of  alive  coset
numbers at any point of an enumeration)  are  bounded  by  `max'.  See
Section~"Coset  Statistics  Terminology",  for  a  discussion  of  the
terminology: *activecosets* and *maxcosets*.

\>`hole:=<val>'{option hole}@{option `hole'}&
Maximum percentage of holes allowed during an enumeration;
`<val>' should be an integer in the range $-1$ to 100.
(Shortest abbreviation: `ho'.)

This is an experimental feature which  allows  an  enumeration  to  be
terminated when the percentage of holes in the table exceeds  a  given
value. In practice, calculating this is very expensive, and  it  tends
to remain constant or  decrease  throughout  an  enumeration.  So  the
feature doesn't seem very useful. The default value of $-1$ turns this
feature off. If you want more details, read the source code.

\enditems

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{ACE Parameter Options controlling ACE Output}

\beginitems

\>`messages:=<val>'{option messages}@{option `messages'}
\>`monitor:=<val>'{option monitor}@{option `monitor'}&
Sets the verbosity of output from {\ACE}; <val> should be an integer.
(Shortest  abbreviation  of  `messages'  is   `mess',   and   shortest
abbreviation of `monitor' is `mon'.)

By default, <val> = 0, for which {\ACE} prints out only a single  line
of information, giving the result of each  enumeration.  If  <val>  is
non-zero then the presentation and the parameters are  echoed  at  the
start of the run, and messages  on  the  enumeration's  status  as  it
progresses are also printed out. The absolute value of <val> sets  the
frequency of the progress messages, with a negative sign turning  hole
monitoring on. Note that, hole monitoring is expensive, so don't  turn
it on unless you really need it.

Note   that,  ordinarily,  one   will   not   see   these    messages:
non-interactively,   these   messages    are    directed    to    file
`ACEData.outfile'   (or   <filename>,   if   option   `aceoutfile   :=
<filename>', or `ao := <filename>', is used), and interactively  these
messages are simply  not  displayed.  However,  one  can  change  this
situation both interactively and   non-interactively  by  setting  the
`InfoLevel' of `InfoACE' to 3 via

\beginexample
gap> SetInfoACELevel(3);

\endexample

Then {\ACE}'s messages are  displayed  prepended  with  ```\#I  '''.
Please refer to Appendix~"The  Meanings  of  ACE's  output  messages",
where the meanings of {\ACE}'s output messages are fully discussed.

\enditems

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{ACE Parameter Options that give Names to the Group and Subgroup}

These options may be safely ignored; they only give names to the group
or subgroup within the {\ACE}  output,  and  have  no  effect  on  the
enumeration itself.

\beginitems

\>`enumeration:=<string>'{option enumeration}@{option `enumeration'}&
Sets the `Group Name' to <string>;  <string>,  must  of  course  be  a
string. (Shortest abbreviation: `enum'.)

The {\ACE} binary has a two-word synonym for this option: `Group Name'
and this is how it is identified in the ``Run  Parameters''  block  of
the {\ACE} output when `messages' has a non-zero  value.  The  default
`Group Name' is `"G"'.

\>`subgroup:=<string>'{option subgroup}@{option `subgroup'}& 
Sets the `Subgroup Name' to <string>; <string> must  of  course  be  a
string. (Shortest abbreviation: `subg'.)

The default `Subgroup Name' is `"H"'.

\enditems

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Options for redirection of ACE Output}

\beginitems

\>`ao:=<filename>'{option ao}@{option `ao'}
\>`aceoutfile:=<filename>'{option aceoutfile!ao synonym}@{option `aceoutfile'}&
Redirects (`a'lters) `o'utput to <filename>; <filename>  should  be  a
string.

Non-interactively, output from {\ACE} is normally directed to a temporary
file whose full path is stored in `ACEData.outfile', which  is  parsed
to produce a coset table or a list of statistics. This  option  causes
{\ACE}'s output to  be  directed  to  <filename>  instead,  presumably
because the user wishes to see (and keep) data output  by  the  {\ACE}
binary,    other    than    the    coset     table     output     from
`ACECosetTableFromGensAndRels' or the statistics output by `ACEStats'.
Please refer to Appendix~"The  Meanings  of  ACE's  output  messages",
where we discuss the meaning of the additional data to be found in the
{\ACE} binary's output. The option `aceoutfile' is a {\GAP}-introduced
synonym for `ao', that is translated to `ao' before submission to  the
{\ACE} binary.  Do  not  use  option  `aceoutfile'  when  running  the
standalone directly. Happily, `ao' can also be regarded as  mnemonical
for `aceoutfile'.

\enditems

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Other Options}

{\ACE} has a number of other options, but the  {\GAP}  user  will  not
ordinarily need them, since, in most  cases,  alternative  interactive
functions exist.  These  remaining  options  have  been  relegated  to
Appendix~"Other ACE Options". The options listed  there  may  be  used
both interactively and non-interactively, but many are  probably  best
used directly via the {\ACE} standalone.

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