Quelle CHAP006.htm Sprache: HTML

products/sources/formale Sprachen/GAP/pkg/ace/htm/CHAP006.htm

<html><head><title>[ACE] 6 Functions for Using ACE Interactively</title></head>
<body text="#000000" bgcolor="#ffffff">
[<a href = "chapters.htm">Up</a>] [<a href ="CHAP005.htm">Previous</a>] [<a href ="CHAP00A.htm">Next</a>] [<a href = "theindex.htm">Index</a>]
<h1>6 Functions for Using ACE Interactively</h1>

<H3>Sections</H3>
<oL>
<li> <A HREF="CHAP006.htm#SECT001">Starting and Stopping Interactive ACE Processes</a>
<li> <A HREF="CHAP006.htm#SECT002">General ACE Modes</a>
<li> <A HREF="CHAP006.htm#SECT003">Interactive ACE Process Utility Functions and Interruption of an Interactive ACE Process</a>
<li> <A HREF="CHAP006.htm#SECT004">Experimentation ACE Modes</a>
<li> <A HREF="CHAP006.htm#SECT005">Interactive Query Functions and an Option Setting Function</a>
<li> <A HREF="CHAP006.htm#SECT006">Interactive Versions of Non-interactive ACE Functions</a>
<li> <A HREF="CHAP006.htm#SECT007">Steering ACE Interactively</a>
<li> <A HREF="CHAP006.htm#SECT008">Primitive ACE Read/Write Functions</a>
</ol>

The user will probably benefit most from interactive use of ACE by
setting the <code>InfoLevel</code> of <code>InfoACE</code> to at least 3
(see <a href="CHAP001.htm#SSEC009.1">InfoACE</a>), particularly if she uses the <code>messages</code>
option with a non-zero value.

Have you read the various options warnings yet? If not, please take
the time to read Section <a href="CHAP001.htm#SECT007">General Warnings regarding the Use of Options</a> which directs you to various important sections of
Chapter <a href="CHAP004.htm">Options for ACE</a>.

We describe in this chapter the functions that manipulate and initiate
interactive ACE processes.

An interactive ACE process is initiated by <code>ACEStart</code> and
terminated via <code>ACEQuit</code>; these functions are described in
Section <a href="CHAP006.htm#SECT001">Starting and Stopping Interactive ACE Processes</a>. <code>ACEStart</code>
also has forms that manipulate an already started interactive ACE
process. <code>ACEStart</code> always returns a positive integer <var>i</var>, which
identifies the interactive ACE process that was initiated or
manipulated.

Most functions (there is one <code>ACEStart</code> exception), that manipulate an
already started interactive ACE process, have a form where the
first argument is the integer <var>i</var> returned by the initiating
<code>ACEStart</code> command, and a second form with one argument fewer (where
the integer <var>i</var> is discovered by a default mechanism, namely by
determining the least integer <var>i</var> for which there is a currently
active interactive ACE process). We will thus commonly say that
``for the <var>i</var>th (or default) interactive ACE process'' a certain
function performs a given action. In each case, it is an error, if <var>i</var>
is not the index of an active interactive process, or there are no
current active interactive processes.

Notes:
The global method of passing options (via <code>PushOptions</code>), should not
be used with any of the interactive functions. In fact, the
<code>OptionsStack</code> should be empty at the time any of the interactive
functions is called.

On <code>quit</code>ting GAP, <code>ACEQuitAll();</code> is executed, which terminates
all active interactive ACE processes. If GAP is killed without
<code>quit</code>ting, before all interactive ACE processes are terminated,
zombie processes (still living child processes whose parents
have died), will result. Since zombie processes do consume resources,
in such an event, the responsible computer user should seek out and
kill the still living <code>ace</code> children (e.g. by piping the output of a
<code>ps</code> with appropriate options, usually <code>aux</code> or <code>ef</code>, to <code>grep ace</code>,
to find the process ids, and then using <code>kill</code>; try <code>man ps</code> and <code>man
kill</code> if these hints are unhelpful).


<h2><a name="SECT001">6.1 Starting and Stopping Interactive ACE Processes</a></h2>

<a name = "SSEC001.1"></a>
<li><code>ACEStart( </code><var>fgens</var><code>, </code><var>rels</var><code>, </code><var>sgens</var><code> [:</code><var>options</var><code>] ) F</code>
<a name = "SSEC001.1"></a>
<li><code>ACEStart( </code><var>i</var><code> [:</code><var>options</var><code>] ) F</code>
<li><code>ACEStart( [:</code><var>options</var><code>] ) F</code>
<li><code>ACEStart( </code><var>i</var><code>, </code><var>fgens</var><code>, </code><var>rels</var><code>, </code><var>sgens</var><code> [:</code><var>options</var><code>] ) F</code>
<li><code>ACEStart( 0 [:</code><var>options</var><code>] ) F</code>
<li><code>ACEStart( 0, </code><var>fgens</var><code>, </code><var>rels</var><code>, </code><var>sgens</var><code> [:</code><var>options</var><code>] ) F</code>
<li><code>ACEStart( 0, </code><var>i</var><code> [:</code><var>options</var><code>] ) F</code>
<li><code>ACEStart( 0, </code><var>i</var><code>, </code><var>fgens</var><code>, </code><var>rels</var><code>, </code><var>sgens</var><code> [:</code><var>options</var><code>] ) F</code>

The variables are: <var>i</var>, a positive integer numbering from 1 that
represents (indexes) an already running interactive ACE process;
<var>fgens</var>, a list of free generators; <var>rels</var>, a list of words in the
generators <var>fgens</var> giving relators for a finitely presented group; and
<var>sgens</var>, a list of subgroup generators, again expressed as words in
the free generators <var>fgens</var>. Each of <var>fgens</var>, <var>rels</var> and <var>sgens</var> are
given in the standard GAP format for finitely presented groups (See
Chapter <a href="../../../doc/ref/chap47.html#X7AA982637E90B35A">Finitely Presented Groups</a> of the GAP Reference
Manual).

All forms of <code>ACEStart</code> accept options described in Chapters <a href="CHAP004.htm">Options for ACE</a> and <a href="CHAP005.htm">Strategy Options for ACE</a>, and Appendix <a href="CHAP00D.htm">Other ACE Options</a>, which are listed behind a colon in the usual way (see
<a href="../../../doc/ref/chap4.html#X78C70489791FDF43">Function Calls</a> in the GAP Reference Manual). The reader is
strongly encouraged to read the introductory sections of
Chapter <a href="CHAP004.htm">Options for ACE</a>, with regard to options. The global
mechanism (via <code>PushOptions</code>) of passing options is not recommended
for use with the interactive ACE interface functions; please ensure
the <code>OptionsStack</code> is empty before calling an interactive ACE
interface function.

The return value (for all forms of <code>ACEStart</code>) is an integer
(numbering from 1) which represents the running process. It is
possible to have more than one interactive process running at once.
The integer returned may be used to index which of these processes an
interactive ACE interface function should be applied to.

The first four forms of <code>ACEStart</code> insert a <code>start</code> (see <a href="CHAP00D.htm#SSEC003.2">option start</a>) directive after the user's options to invoke an enumeration.
The last four forms, with <code>0</code> as first argument, do not insert a
<code>start</code> directive. Moreover, the last 3 forms of <code>ACEStart</code>, with <code>0</code>
as first argument only differ from the corresponding forms of
<code>ACEStart</code> without the <code>0</code> argument, in that they do not insert a
<code>start</code> directive. <code>ACEStart(0)</code>, however, is special; unlike the
no-argument form of <code>ACEStart</code> it invokes a new interactive ACE
process. We will now further describe each form of <code>ACEStart</code>, in the
order they appear above.

The first form of <code>ACEStart</code> (on three arguments) is the usual way to
start an interactive ACE process.

When <code>ACEStart</code> is called with one positive integer argument <var>i</var> it
starts a new enumeration on the <var>i</var>th running process, i.e. it scrubs
a previously generated table and starts from scratch with the same
parameters (i.e. the same arguments and options); except that if new
options are included these will modify those given previously. The
only reason for doing such a thing, without new options, is to perhaps
compare timings of runs (a second run is quicker because memory has
already been allocated). If you are interested in this sort of
information, however, you may be better off dealing directly with the
standalone.

When <code>ACEStart</code> is called with no arguments it finds the least
positive integer <var>i</var> for which an interactive process is running and
applies <code>ACEStart(</code><var>i</var><code>)</code>. (Most users will only run one interactive
process at a time. Hence, <code>ACEStart()</code> will be a useful shortcut for
<code>ACEStart(1)</code>.)

The fourth form of <code>ACEStart</code> on four arguments, invokes a new
enumeration on the <var>i</var>th running process, with new generators <var>fgens</var>,
relators <var>rels</var> and subgroup generators <var>sgens</var>. This is provided so a
user can re-use an already running process, rather than start a new
process. This may be useful when pseudo-ttys are a scarce resource.
See the notes for the non-interactive <code>ACECosetTable</code>
(<a href="CHAP001.htm#SSEC002.1">ACECosetTableFromGensAndRels</a>) which demonstrates an application of
a usage of this and the following form of <code>ACEStart</code> in a loop.

The fifth form of <code>ACEStart</code> (on the one argument: <code>0</code>) initiates an
interactive ACE process, processes any user options, but does not
insert a <code>start</code> (see <a href="CHAP00D.htm#SSEC003.2">option start</a>) directive. This form is mainly
for gurus who are familiar with the ACE standalone and who wish, at
least initially, to communicate with ACE using the primitive
read/write tools of Section <a href="CHAP006.htm#SECT008">Primitive ACE Read/Write Functions</a>. In
this case, after the group generators, relators, and subgroup
generators have been set in the ACE process, invocations of any of
<code>ACEGroupGenerators</code> (see <a href="CHAP006.htm#SSEC005.1">ACEGroupGenerators</a>), <code>ACERelators</code>
(see <a href="CHAP006.htm#SSEC005.2">ACERelators</a>), <code>ACESubgroupGenerators</code>
(see <a href="CHAP006.htm#SSEC005.3">ACESubgroupGenerators</a>), or <code>ACEParameters</code>
(see <a href="CHAP006.htm#SSEC005.10">ACEParameters</a>) will establish the corresponding GAP values.
Be warned, though, that unless one of the general ACE modes (see
Section <a href="CHAP006.htm#SECT002">General ACE modes</a>): <code>ACEStart</code> (without a zero argument),
<code>ACERedo</code> (see <a href="CHAP006.htm#SSEC002.3">ACERedo</a>) or <code>ACEContinue</code> (see <a href="CHAP006.htm#SSEC002.2">ACEContinue</a>), or one
of the mode options: <code>start</code> (see <a href="CHAP00D.htm#SSEC003.2">option start</a>), <code>redo</code> (see <a href="CHAP00D.htm#SSEC003.3">option redo</a>) or <code>continu</code> (see <a href="CHAP00D.htm#SSEC003.4">option continu</a>), has been invoked since the
last change of any parameter options (see <a href="CHAP004.htm#SSEC012.1">ACEParameterOptions</a>), some
of the values reported by <code>ACEParameters</code> may well be incorrect.

The sixth form of <code>ACEStart</code> (on four arguments), is like the first
form of <code>ACEStart</code> (on three arguments), except that it does not
insert a <code>start</code> (see <a href="CHAP00D.htm#SSEC003.2">option start</a>) directive. It initiates an
interactive ACE process, with a presentation defined by its last 3
arguments.

The seventh form of <code>ACEStart</code> (on two arguments), is like the second
form of <code>ACEStart</code> (on one argument), except that it does not insert a
<code>start</code> (see <a href="CHAP00D.htm#SSEC003.2">option start</a>) directive. It processes any new options
for the <var>i</var>th interactive ACE process. <code>ACEStart(0, </code><var>i</var><code> [:
</code><var>options</var><code> ] )</code>, is similar to <code>SetACEOptions(</code><var>i</var><code> [: </code><var>options</var><code> ] )</code>
(see <a href="CHAP006.htm#SSEC005.8">SetACEOptions</a>), but unlike the latter does not invoke a general
mode (see Section <a href="CHAP006.htm#SECT002">General ACE Modes</a>).

The last form of <code>ACEStart</code> (on five arguments), is like the fourth
form of <code>ACEStart</code> (on four arguments), except that it does not insert
a <code>start</code> (see <a href="CHAP00D.htm#SSEC003.2">option start</a>) directive. It re-uses an existing
interactive ACE process, with a new presentation. There is no form
of <code>ACEStart</code> with the same functionality as this form, where the <var>i</var>
argument is omitted.

Note:
When an interactive ACE process is initiated by <code>ACEStart</code> a
process number <var>i</var> is assigned to it (the integer <var>i</var> returned by the
<code>ACEStart</code> command), an ACE (binary) process (in the UNIX sense) is
started up, a GAP iostream is assigned to communicate with the
ACE (binary) process, and the essential ``defining'' data
associated with the interactive ACE process is saved in
<code>ACEData.io[</code><var>i</var><code>]</code> (see <a href="CHAP001.htm#SSEC008.1">ACEData</a> for precisely what is saved).

<a name = "SSEC001.2"></a>
<li><code>ACEQuit( </code><var>i</var><code> ) F</code>
<a name = "SSEC001.2"></a>
<li><code>ACEQuit() F</code>

terminate an interactive ACE process, where <var>i</var> is the integer
returned by <code>ACEStart</code> when the process was started. If the second
form is used (i.e. without arguments) then the interactive process of
least index that is still running is terminated.

Note:
<code>ACEQuit(</code><var>i</var><code>)</code> terminates the ACE (binary) process of interactive
ACE process <var>i</var>, and closes its GAP iostream, and unbinds the
record <code>ACEData.io[</code><var>i</var><code>]</code> (see <a href="CHAP006.htm#SSEC001.1">ACEStart</a> note).

It can happen that the ACE (binary) process, and hence the GAP
iostream assigned to communicate with it, can die, e.g. by the user
typing a <code>Ctrl-C</code> while the ACE (binary) process is engaged in a
long calculation. <code>IsACEProcessAlive</code> (see <a href="CHAP006.htm#SSEC003.3">IsACEProcessAlive</a>) is
provided to check the status of the GAP iostream (and hence the
status of the ACE (binary) process it was communicating with); in
the case that it is indeed dead, <code>ACEResurrectProcess</code>
(see <a href="CHAP006.htm#SSEC003.4">ACEResurrectProcess</a>) may be used to start a new ACE (binary)
process and assign a new GAP iostream to communicate with it, by
using the ``defining'' data of the interactive ACE process saved in
<code>ACEData.io[</code><var>i</var><code>]</code>.

<a name = "SSEC001.3"></a>
<li><code>ACEQuitAll() F</code>

is provided as a convenience, to terminate all active interactive
ACE processes with a single command. It is equivalent to executing
<code>ACEQuit(</code><var>i</var><code>)</code> for all active interactive ACE processes <var>i</var>
(see <a href="CHAP006.htm#SSEC001.2">ACEQuit</a>).


<h2><a name="SECT002">6.2 General ACE Modes</a></h2>

For our purposes, we define an interactive ACE interface command to
be an ACE mode, if it delivers an enumeration result (see
Section <a href="CHAP00A.htm#SECT002">Results messages</a>). Thus, <code>ACEStart</code> (see <a href="CHAP006.htm#SSEC001.1">ACEStart</a>), except
when called with the argument 0, and the commands <code>ACERedo</code> and
<code>ACEContinue</code> which we describe below are ACE modes; we call these
general ACE modes. Additionally, there are two other commands
which deliver enumeration results: <code>ACEAllEquivPresentations</code>
(see <a href="CHAP006.htm#SSEC004.1">ACEAllEquivPresentations</a>) and <code>ACERandomEquivPresentations</code>
(see <a href="CHAP006.htm#SSEC004.2">ACERandomEquivPresentations</a>); we call these ``experimentation''
ACE modes and describe them in Section <a href="CHAP006.htm#SECT004">Experimentation ACE Modes</a>.

Guru Note:
The ACE standalone uses the term <code>mode</code> in a slightly different
sense. There, the commands: <code>start</code>, <code>redo</code> or <code>continue</code>, put the
ACE enumerator in <code>start mode</code>, <code>redo mode</code> or <code>continue mode</code>. In
this manual, we have used the term to mean the command itself, and
generalised it to include any command that produces enumeration
results.

After changing any of ACE's parameters, one of three general
modes is possible: one may be able to ``continue'' via <code>ACEContinue</code>
(see <a href="CHAP006.htm#SSEC002.2">ACEContinue</a>), or ``redo'' via <code>ACERedo</code> (see <a href="CHAP006.htm#SSEC002.3">ACERedo</a>), or if
neither of these is possible one may have to re-``start'' the
enumeration via <code>ACEStart</code> (see <a href="CHAP006.htm#SSEC001.1">ACEStart</a>). Generally, the
appropriate mode is invoked automatically when options are changed; so
most users should be able to ignore the following three functions.

<a name = "SSEC002.1"></a>
<li><code>ACEModes( </code><var>i</var><code> ) F</code>
<li><code>ACEModes() F</code>

for the <var>i</var>th (or default) interactive ACE process, return a record
whose fields are the modes <code>ACEStart</code>, <code>ACEContinue</code> and <code>ACERedo</code>,
and whose values are <code>true</code> if the mode is possible for the process
and <code>false</code> otherwise.

<a name = "SSEC002.2"></a>
<li><code>ACEContinue( </code><var>i</var><code> [:</code><var>options</var><code>] ) F</code>
<li><code>ACEContinue( [:</code><var>options</var><code>] ) F</code>

for the <var>i</var>th (or default) interactive ACE process, apply any
<var>options</var> and then ``continue'' the current enumeration, building upon
the existing table. If a previous run stopped without producing a
finite index you can, in principle, change any of the options and
continue on. Of course, if you make any changes which invalidate the
current table, you won't be allowed to ACEContinue and an error will
be raised. However, after <code>quit</code>ting the <code>break</code>-loop, the interactive
ACE process should normally still be active; after doing so, run
<code>ACEModes</code> (see <a href="CHAP006.htm#SSEC002.1">ACEModes</a>) to see which of <code>ACERedo</code> or <code>ACEStart</code> is
possible.

<a name = "SSEC002.3"></a>
<li><code>ACERedo( </code><var>i</var><code> [:</code><var>options</var><code>] ) F</code>
<li><code>ACERedo( [:</code><var>options</var><code>] ) F</code>

for the <var>i</var>th (or default) interactive ACE process, apply any
<var>options</var> and then ``redo'' the current enumeration from coset 1
(i.e., the subgroup), keeping any existing information in the table.

Notes:
The difference between <code>ACEContinue</code> and <code>ACERedo</code> is somewhat
technical, and the user should regard it as a mode that is a little
more expensive than <code>ACEContinue</code> but cheaper than <code>ACEStart</code>.
<code>ACERedo</code> is really intended for the case where additional relators
and/or subgroup generators have been introduced; the current table,
which may be incomplete or exhibit a finite index, is still ``valid''.
However, the new data may allow the enumeration to complete, or cause
a collapse to a smaller index. In some cases, <code>ACERedo</code> may not be
possible and an error will be raised; in this case, <code>quit</code> the
<code>break</code>-loop, and try <code>ACEStart</code>, which will discard the current table
and re-``start'' the enumeration.


<h2><a name="SECT003">6.3 Interactive ACE Process Utility Functions and Interruption of an Interactive ACE Process</a></h2>

<a name = "SSEC003.1"></a>
<li><code>ACEProcessIndex( </code><var>i</var><code> ) F</code>
<li><code>ACEProcessIndex() F</code>

With argument <var>i</var>, which must be a positive integer, <code>ACEProcessIndex</code>
returns <var>i</var> if it corresponds to an active interactive process, or
raises an error. With no arguments it returns the default active
interactive process or returns <code>fail</code> and emits a warning message to
<code>Info</code> at <code>InfoACE</code> or <code>InfoWarning</code> level 1.

Note:
Essentially, an interactive ACE process <var>i</var> is ``active'' if
<code>ACEData.io[</code><var>i</var><code>]</code> is bound (i.e. we still have some data telling us
about it). Also see <a href="CHAP006.htm#SSEC001.1">ACEStart</a> note.

<a name = "SSEC003.2"></a>
<li><code>ACEProcessIndices() F</code>

returns the list of integer indices of all active interactive ACE
processes (see <a href="CHAP006.htm#SSEC003.1">ACEProcessIndex</a> for the meaning of ``active'').

<a name = "SSEC003.3"></a>
<li><code>IsACEProcessAlive( </code><var>i</var><code> ) F</code>
<li><code>IsACEProcessAlive() F</code>

return <code>true</code> if the GAP iostream of the <var>i</var>th (or default)
interactive ACE process started by <code>ACEStart</code> is alive (i.e. can
still be written to), or <code>false</code>, otherwise. (See the notes
for <a href="CHAP006.htm#SSEC001.1">ACEStart</a> and <a href="CHAP006.htm#SSEC001.2">ACEQuit</a>.)

<a name = "I0"></a>

<a name = "I1"></a>

If the user does not yet have a <code>gap></code> prompt then usually ACE is
still away doing something and an ACE interface function is still
waiting for a reply from ACE. Typing a <code>Ctrl-C</code> (i.e. holding down
the <code>Ctrl</code> key and typing <code>c</code>) will stop the waiting and send GAP
into a <code>break</code>-loop, from which one has no option but to <code>quit;</code>. The
typing of <code>Ctrl-C</code>, in such a circumstance, usually causes the stream
of the interactive ACE process to die; to check this we provide
<code>IsACEProcessAlive</code> (see <a href="CHAP006.htm#SSEC003.3">IsACEProcessAlive</a>). If the stream of an
interactive ACE process, indexed by <var>i</var>, say, has died, it may
still be possible to recover enough of the state, before the death of
the stream, from the information stored in the <code>ACEData.io[</code><var>i</var><code>]</code>
record (see Section <a href="CHAP001.htm#SECT008">The ACEData Record</a>). For such a purpose, we have
provided <code>ACEResurrectProcess</code> (see <a href="CHAP006.htm#SSEC003.4">ACEResurrectProcess</a>).

The GAP iostream of an interactive ACE process will also die if
the ACE binary has a segmentation fault. We do hope that this never
happens to you, but if it does and the failure is reproducible, then
it's a bug and we'd like to know about it. Please read the file <code>README.md</code>
that comes with the ACE package to find out what to include in a
bug report and who to email it to.

<a name = "SSEC003.4"></a>
<li><code>ACEResurrectProcess( </code><var>i</var><code> [: </code><var>options</var><code>] ) F</code>
<li><code>ACEResurrectProcess( [: </code><var>options</var><code>] ) F</code>

re-generate the GAP iostream of the <var>i</var>th (or default) interactive
ACE process started by <code>ACEStart</code> (see <a href="CHAP006.htm#SSEC001.1">ACEStart</a>, the final note,
in particular), and try to recover as much as possible of the previous
state from saved values of the process's arguments and parameter
options. The possible <var>options</var> here are <code>use</code> and <code>useboth</code> which are
described in detail below.

The arguments of the <var>i</var>th interactive ACE process are stored in
<code>ACEData.io[</code><var>i</var><code>].args</code>, a record with fields <code>fgens</code>, <code>rels</code> and
<code>sgens</code>, which are the GAP group generators, relators and subgroup
generators, respectively (see Section <a href="CHAP001.htm#SECT008">The ACEData Record</a>). Option
information is saved in <code>ACEData.io[</code><var>i</var><code>].options</code> when a user uses an
interactive ACE interface function with options or uses
<code>SetACEOptions</code> (see <a href="CHAP006.htm#SSEC005.8">SetACEOptions</a>). Parameter option information is
saved in <code>ACEData.io[</code><var>i</var><code>].parameters</code> if <code>ACEParameters</code> (see <a href="CHAP006.htm#SSEC005.10">ACEParameters</a>)
is used to extract from ACE the current values of the ACE
parameter options (this is generally less reliable unless one of the
general ACE modes (see Section <a href="CHAP006.htm#SECT002">General ACE Modes</a>), has been run
previously).

By default, <code>ACEResurrectProcess</code> recovers parameter option
information from <code>ACEData.io[</code><var>i</var><code>].options</code> if it is bound, or from
<code>ACEData.io[</code><var>i</var><code>].parameters</code> if it is bound, otherwise. The
<code>ACEData.io[</code><var>i</var><code>].options</code> record, however, is first filtered for
parameter and strategy options (see Sections <a href="CHAP004.htm#SSEC012.1">ACEParameterOptions</a>
and <a href="CHAP004.htm#SECT009">The ACEStrategyOptions list</a>) and the <code>echo</code> option (see <a href="CHAP004.htm#SSEC011.12">option echo</a>). To alter this behaviour, the user is provided two options:


<dl compact>

<dt> <code>use := </code><var>useList</var><code></code><dd> <var>useList</var> may contain one or both of
<code>"options"</code> and <code>"parameters"</code>. By default, <code>use = ["options",
"parameters"]</code>.

<dt> <code>useboth</code> <dd> (A boolean option). By default, <code>useboth = false</code>.

</dl>

If <code>useboth = true</code>, <code>SetACEOptions</code> (see <a href="CHAP006.htm#SSEC005.8">SetACEOptions</a>) is applied
to the <var>i</var>th interactive ACE process with each
<code>ACEData.io[</code><var>i</var><code>].(</code><var>field</var><code>)</code> for each <var>field</var> (<code>"options"</code> or
<code>"parameters"</code>) that is bound and in <var>useList</var>, in the order implied
by <var>useList</var>. If <code>useboth = false</code>, <code>SetACEOptions</code> is applied with
<code>ACEData.io[</code><var>i</var><code>].(</code><var>field</var><code>)</code> for only the first <var>field</var> that is bound
in <var>useList</var>. The current value of the <code>echo</code> option is also preserved
(no matter what values the user chooses for the <code>use</code> and <code>useboth</code>
options).

Notes:
Do not use general ACE options with <code>ACEResurrectProcess</code>; they
will only be superseded by those options recovered from
<code>ACEData.io[</code><var>i</var><code>].options</code> and/or <code>ACEData.io[</code><var>i</var><code>].parameters</code>.
Instead, call <code>SetACEOptions</code> first (or afterwards). When called prior
to <code>ACEResurrectProcess</code>, <code>SetACEOptions</code> will emit a warning that the
stream is dead; despite this, the <code>ACEData.io[</code><var>i</var><code>].options</code> will be
updated.

<code>ACEResurrectProcess</code> does not invoke an ACE mode (see
Section <a href="CHAP006.htm#SECT002">General ACE Modes</a>). This leaves the user free to use
<code>SetACEOptions</code> (which does invoke an ACE mode) to further modify
options afterwards.

<a name = "SSEC003.5"></a>
<li><code>ToACEGroupGenerators( </code><var>fgens</var><code> ) F</code>

This function produces, from a GAP list <var>fgens</var> of free group
generators, the ACE directive string required by the <code>group</code>
(see <a href="CHAP00D.htm#SSEC002.1">option group</a>) option. (The <code>group</code> option may be used to define
the equivalent of <var>fgens</var> in an ACE process.)

<a name = "SSEC003.6"></a>
<li><code>ToACEWords( </code><var>fgens</var><code>, </code><var>words</var><code> ) F</code>

This function produces, from a GAP list <var>words</var> in free group
generators <var>fgens</var>, a string that represents those <var>words</var> as an
ACE list of words. <code>ToACEWords</code> may be used to provide suitable
values for the options <code>relators</code> (see <a href="CHAP00D.htm#SSEC002.2">option relators</a>),
<code>generators</code> (see <a href="CHAP00D.htm#SSEC002.3">option generators</a>), <code>sg</code> (see <a href="CHAP00D.htm#SSEC002.4">option sg</a>), and
<code>rl</code> (see <a href="CHAP00D.htm#SSEC002.5">option rl</a>).


<h2><a name="SECT004">6.4 Experimentation ACE Modes</a></h2>

Now we describe the two experimentation modes. The term mode was
defined in Section <a href="CHAP006.htm#SECT002">General ACE Modes</a>.

<a name = "SSEC004.1"></a>
<li><code>ACEAllEquivPresentations( </code><var>i</var><code>, </code><var>val</var><code> ) F</code>
<li><code>ACEAllEquivPresentations( </code><var>val</var><code> ) F</code>

for the <var>i</var>th (or default) interactive ACE process, generates and
tests an enumeration for combinations of relator ordering, relator
rotations, and relator inversions; <var>val</var> is in the integer range 1 to
7.

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

Before we describe the GAP output of <code>ACEAllEquivPresentations</code> let
us spend some time considering what happens before the ACE binary
output is parsed.

The <code>ACEAllEquivPresentations</code> command first performs a ``priming
run'' using the options as they stand. In particular, the <code>asis</code> and
<code>messages</code> options are honoured.

It then turns <code>asis</code> (see <a href="CHAP004.htm#SSEC013.1">option asis</a>) on and <code>messages</code>
(see <a href="CHAP004.htm#SSEC018.1">option messages</a>) off (i.e. sets <code>messages</code> to 0), and generates
and tests the requested equivalent presentations. The maximum and
minimum values attained by <code>m</code> (the maximum number of coset numbers
defined at any stage) and <code>t</code> (the total number of coset numbers
defined) are tracked, and each time the statistics are better than
what we've already seen, the ACE binary emits a summary result line
for the relators used. See Appendix <a href="CHAP00A.htm">The Meanings of ACE's output messages for a discussion of the statistics m and t. To observe
these messages set the <code>InfoLevel</code> of <code>InfoACE</code> to 3; and it's
recommended that you do this so that you get some idea of what the
ACE binary is doing.

The order in which the equivalent presentations are generated and
tested has no particular significance, but note that the presentation
as given after the initial priming run) is the last presentation
to be generated and tested, so that the group's relators are left
``unchanged'' by running the <code>ACEAllEquivPresentations</code> command.

As discussed by Cannon, Dimino, Havas and Watson <a href="biblio.htm#CDHW73"><cite>CDHW73</cite></a> and
Havas and Ramsay <a href="biblio.htm#HR01"><cite>HR01</cite></a> 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:

<ul>

<li> the number of runs which yielded a finite index;

<li> the total number of runs (excluding the priming run); and

<li> the range of values observed for <code>m</code> and <code>t</code>.

</ul>

As an example (drawn from the discussion in <a href="biblio.htm#HR99ace"><cite>HR99ace</cite></a>) consider the
enumeration of the 448 coset numbers of the subgroup
〈a2,a−1b 〉 of the group
 <table border="0" width="100%"><tr><td><table align="center" cellspacing="0" cellpadding="2"><tr><td nowrap="nowrap" align="center"> (8,7 | 2,3) = 〈a,b | a8 = b7 = (ab)2 = (a−1b)3 = 1 〉·</td></tr></table></td></tr></table>
There are 4!=24 relator orderings and 24=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 <var>val</var> = 7 (resp. 3), 24·16·4=1536 (resp. 16·4=64)
equivalent presentations are tested.

Now we describe the output of <code>ACEAllEquivPresentations</code>; it is a
record with fields:


<dl compact>

<dt> <code>primingResult</code> <dd> the ACE enumeration result message (see
Section <a href="CHAP00A.htm#SECT002">Results Messages</a>) of the priming run;

<dt> <code>primingStats</code> <dd> the enumeration result of the priming run as a
GAP record with fields <code>index</code>, <code>cputime</code>, <code>cputimeUnits</code>,
<code>activecosets</code>, <code>maxcosets</code> and <code>totcosets</code>, exactly as for the record
returned by <code>ACEStats</code> (see <a href="CHAP001.htm#SSEC003.1">ACEStats</a>);

<dt> <code>equivRuns</code> <dd> a list of data records, one for each progressively
``best'' run, where each record has fields:

<dt> <code>rels</code><dd> the relators in the order used for the run,

<dt> <code>enumResult</code><dd> the ACE enumeration result message (see
Section <a href="CHAP00A.htm#SECT002">Results Messages</a>) of the run, and

<dt> <code>stats</code><dd> the enumeration result as a GAP record exactly like
the record returned by <code>ACEStats</code> (see <a href="CHAP001.htm#SSEC003.1">ACEStats</a>);

<dt> <code>summary</code> <dd> a record with fields:

<dt> <code>successes</code><dd> the total number of successful (i.e. having finite
enumeration index) runs,

<dt> <code>runs</code><dd> the total number of equivalent presentation runs
executed,

<dt> <code>maxcosetsRange</code><dd> the range of values as a GAP list inside
which each <code>equivRuns[</code><var>i</var><code>].maxcosets</code> lies, and

<dt> <code>totcosetsRange</code><dd> the range of values as a GAP list inside
which each <code>equivRuns[</code><var>i</var><code>].totcosets</code> lies.

</dl>

Notes:
In general, the length of the <code>equivRuns</code> field list will be less than
the number of runs executed.

There is no way to stop the <code>ACEAllEquivPresentations</code> command before
it has completed, other than killing the task. So do a reality check
beforehand on the size of the search space and the time for each
enumeration. If you are interested in finding a ``good'' enumeration,
it can be very helpful, in terms of running time, to put a tight limit
on the number of coset numbers via the <code>max</code> option. You may also have
to set <code>compaction</code> = 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
<code>ACERandomEquivPresentations</code> command.

<a name = "SSEC004.2"></a>
<li><code>ACERandomEquivPresentations( </code><var>i</var><code>, </code><var>val</var><code> ) F</code>
<li><code>ACERandomEquivPresentations( </code><var>val</var><code> ) F</code>
<li><code>ACERandomEquivPresentations( </code><var>i</var><code>, [</code><var>val</var><code>] ) F</code>
<li><code>ACERandomEquivPresentations( [</code><var>val</var><code>] ) F</code>
<li><code>ACERandomEquivPresentations( </code><var>i</var><code>, [</code><var>val</var><code>, </code><var>Npresentations</var><code>] ) F</code>
<li><code>ACERandomEquivPresentations( [</code><var>val</var><code>, </code><var>Npresentations</var><code>] ) F</code>

for the <var>i</var>th (or default) interactive ACE process, generates and
tests up to <var>Npresentations</var> (or 8, in the first 4 forms) random
presentations; <var>val</var>, an integer in the range 1 to 7, acts as for
<code>ACEAllEquivPresentations</code> and <var>Npresentations</var>, when given, should be
a positive integer.

The routine first turns <code>asis</code> (see <a href="CHAP004.htm#SSEC013.1">option asis</a>) on and <code>messages</code>
(see <a href="CHAP004.htm#SSEC018.1">option messages</a>) off (i.e. sets <code>messages</code> to 0), and then
generates and tests the requested number of random equivalent
presentations. For each presentation, the relators used and the
summary result line are printed by ACE. To observe these messages
set the <code>InfoLevel</code> of <code>InfoACE</code> to at least 3.

<code>ACERandomEquivPresentations</code> parses the ACE messages, translating
them to GAP, and thus returns a list of records (similar to the
field <code>equivRuns</code> of the returned record of
<code>ACEAllEquivPresentations</code>). Each record of the returned list is the
data derived from a presentation run and has fields:


<dl compact>

<dt> <code>rels</code><dd> the relators in the order used for the run,

<dt> <code>enumResult</code><dd> the ACE enumeration result message (see
Section <a href="CHAP00A.htm#SECT002">Results Messages</a>) of the run, and

<dt> <code>stats</code><dd> the enumeration result as a GAP record exactly like
the record returned by <code>ACEStats</code> (see <a href="CHAP001.htm#SSEC003.1">ACEStats</a>).

</dl>

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 <code>ACERandomEquivPresentations</code> command completes, the
presentation active is the last one generated.

Guru Notes:
It might appear that neglecting to restore the original presentation
is an error. In fact, it is a useful feature! Suppose that the space
of equivalent presentations is too large to exhaustively test. As
noted in the entry for <code>ACEAllEquivPresentations</code>, we can start up
multiple copies of <code>ACEAllEquivPresentations</code> at random points in the
search-space. Manually generating <code>random</code> equivalent presentations to
serve as starting-points is tedious and error-prone. The
<code>ACERandomEquivPresentations</code> command provides a simple solution;
simply run <code>ACERandomEquivPresentations(</code><var>i</var><code>, 7);</code> before
<code>ACEAllEquivPresentations(</code><var>i</var><code>, 7);</code>.


<h2><a name="SECT005">6.5 Interactive Query Functions and an Option Setting Function</a></h2>

<a name = "SSEC005.1"></a>
<li><code>ACEGroupGenerators( </code><var>i</var><code> ) F</code>
<li><code>ACEGroupGenerators() F</code>

return the GAP group generators of the <var>i</var>th (or default)
interactive ACE process. If no generators have been saved for the
interactive ACE process, possibly because the process was started
via <code>ACEStart(0);</code> (see <a href="CHAP006.htm#SSEC001.1">ACEStart</a>), the ACE process is
interrogated, and the equivalent in GAP is saved and returned.
Essentially, <code>ACEGroupGenerators(</code><var>i</var><code>)</code> interrogates ACE and
establishes <code>ACEData.io[</code><var>i</var><code>].args.fgens</code>, if necessary, and returns
<code>ACEData.io[</code><var>i</var><code>].args.fgens</code>. As a side-effect, if any of the
remaining fields of <code>ACEData.io[</code><var>i</var><code>].args</code> or
<code>ACEData.io[</code><var>i</var><code>].acegens</code> are unset, they are also set. Note that
GAP provides <code>GroupWithGenerators</code> (see <a href="../../../doc/ref/chap39.html#X8589EF9C7B658B94">GroupWithGenerators</a>
in the GAP Reference Manual) to establish a free group on a given
set of already-defined generators.

<a name = "SSEC005.2"></a>
<li><code>ACERelators( </code><var>i</var><code> ) F</code>
<li><code>ACERelators() F</code>

return the GAP relators of the <var>i</var>th (or default) interactive
ACE process. If no relators have been saved for the interactive
ACE process, possibly because the process was started via
<code>ACEStart(0);</code> (see <a href="CHAP006.htm#SSEC001.1">ACEStart</a>), the ACE process is interrogated,
the equivalent in GAP is saved and returned. Essentially,
<code>ACERelators(</code><var>i</var><code>)</code> interrogates ACE and establishes
<code>ACEData.io[</code><var>i</var><code>].args.rels</code>, if necessary, and returns
<code>ACEData.io[</code><var>i</var><code>].args.rels</code>. As a side-effect, if any of the remaining
fields of <code>ACEData.io[</code><var>i</var><code>].args</code> or <code>ACEData.io[</code><var>i</var><code>].acegens</code> are
unset, they are also set.

<a name = "SSEC005.3"></a>
<li><code>ACESubgroupGenerators( </code><var>i</var><code> ) F</code>
<li><code>ACESubgroupGenerators() F</code>

return the GAP subgroup generators of the <var>i</var>th (or default)
interactive ACE process. If no subgroup generators have been saved
for the interactive ACE process, possibly because the process was
started via <code>ACEStart(0);</code> (see <a href="CHAP006.htm#SSEC001.1">ACEStart</a>), the ACE process is
interrogated, the equivalent in GAP is saved and returned.
Essentially, <code>ACESubgroupGenerators(</code><var>i</var><code>)</code> interrogates ACE and
establishes <code>ACEData.io[</code><var>i</var><code>].args.sgens</code>, if necessary, and returns
<code>ACEData.io[</code><var>i</var><code>].args.sgens</code>. As a side-effect, if any of the
remaining fields of <code>ACEData.io[</code><var>i</var><code>].args</code> or
<code>ACEData.io[</code><var>i</var><code>].acegens</code> are unset, they are also set.

<a name = "SSEC005.4"></a>
<li><code>DisplayACEArgs( </code><var>i</var><code> ) F</code>
<li><code>DisplayACEArgs() F</code>

display the arguments (i.e. <var>fgens</var>, <var>rels</var> and <var>sgens</var>) of the <var>i</var>th
(or default) process started by <code>ACEStart</code>. In fact,
<code>DisplayACEArgs(</code><var>i</var><code>)</code> is just a pretty-printer of the
<code>ACEData.io[</code><var>i</var><code>].args</code> record. Use <code>GetACEArgs</code> (see <a href="CHAP006.htm#SSEC005.7">GetACEOptions</a>)
in assignments. Unlike <code>ACEGroupGenerators</code>
(see <a href="CHAP006.htm#SSEC005.1">ACEGroupGenerators</a>), <code>ACERelators</code> (see <a href="CHAP006.htm#SSEC005.2">ACERelators</a>) and
<code>ACESubgroupGenerators</code> (see <a href="CHAP006.htm#SSEC005.3">ACESubgroupGenerators</a>),
<code>DisplayACEArgs</code> does not have the side-effect of setting any of the
fields of <code>ACEData.io[</code><var>i</var><code>].args</code> if they are unset.

<a name = "SSEC005.5"></a>
<li><code>GetACEArgs( </code><var>i</var><code> ) F</code>
<li><code>GetACEArgs() F</code>

return a record of the current arguments (i.e. <var>fgens</var>, <var>rels</var> and
<var>sgens</var>) of the <var>i</var>th (or default) process started by <code>ACEStart</code>. In
fact, <code>GetACEOptions(</code><var>i</var><code>)</code> simply returns the <code>ACEData.io[</code><var>i</var><code>].args</code>
record, or an empty record if that record is unbound. Unlike
<code>ACEGroupGenerators</code> (see <a href="CHAP006.htm#SSEC005.1">ACEGroupGenerators</a>), <code>ACERelators</code>
(see <a href="CHAP006.htm#SSEC005.2">ACERelators</a>) and <code>ACESubgroupGenerators</code>
(see <a href="CHAP006.htm#SSEC005.3">ACESubgroupGenerators</a>), <code>GetACEOptions</code> does not have the
side-effect of setting any of the fields of <code>ACEData.io[</code><var>i</var><code>].args</code> if
they are unset.

<a name = "SSEC005.6"></a>
<li><code>DisplayACEOptions( </code><var>i</var><code> ) F</code>
<li><code>DisplayACEOptions() F</code>

display the options, explicitly set by the user, of the <var>i</var>th (or default) process started by
<code>ACEStart</code>. In fact, <code>DisplayACEOptions(</code><var>i</var><code>)</code> is just a pretty-printer
of the <code>ACEData.io[</code><var>i</var><code>].options</code> record. Use <code>GetACEOptions</code>
(see <a href="CHAP006.htm#SSEC005.7">GetACEOptions</a>) in assignments. Please note that no-value ACE
options will appear with the assigned value <code>true</code> (see
Section <a href="CHAP004.htm#SECT006">Interpretation of ACE Options</a> for how the ACE interface
functions interpret such options).

Notes:
Any options set via <code>ACEWrite</code> (see <a href="CHAP006.htm#SSEC008.1">ACEWrite</a>) will not be
displayed. Also, recall that if ACE is not given any options it
uses the <code>default</code> strategy (see Section <a href="CHAP004.htm#SECT005">What happens if no ACE Strategy Option or if no ACE Option is passed</a>). To discover the
various settings of the ACE Parameter Options
(see <a href="CHAP004.htm#SSEC012.1">ACEParameterOptions</a>) in vogue for the ACE process, use
<code>ACEParameters</code> (see <a href="CHAP006.htm#SSEC005.10">ACEParameters</a>).

<a name = "SSEC005.7"></a>
<li><code>GetACEOptions( </code><var>i</var><code> ) F</code>
<li><code>GetACEOptions() F</code>

return a record of the current options (those that have been
explicitly set by the user) of the <var>i</var>th (or default) process started
by <code>ACEStart</code>. Please note that no-value ACE options will appear
with the assigned value <code>true</code> (see Section <a href="CHAP004.htm#SECT006">Interpretation of ACE Options</a> for how the ACE interface functions interpret such
options). The notes applying to <code>DisplayACEOptions</code>
(see <a href="CHAP006.htm#SSEC005.6">DisplayACEOptions</a>) also apply here.

<a name = "SSEC005.8"></a>
<li><code>SetACEOptions( </code><var>i</var><code> [:</code><var>options</var><code>] ) F</code>
<li><code>SetACEOptions( [:</code><var>options</var><code>] ) F</code>

modify the current options of the <var>i</var>th (or default) process started
by <code>ACEStart</code>. Please ensure that the <code>OptionsStack</code> is empty before
calling <code>SetACEOptions</code>, otherwise the options already present on the
<code>OptionsStack</code> will also be ``seen''. All interactive ACE interface
functions that accept options, actually call an internal version of
<code>SetACEOptions</code>; so, it is generally important to keep the
<code>OptionsStack</code> clear while working with ACE interactively.

After setting the options passed, the first mode of the following:
<code>ACEContinue</code> (see <a href="CHAP006.htm#SSEC002.2">ACEContinue</a>), <code>ACERedo</code> (see <a href="CHAP006.htm#SSEC002.3">ACERedo</a>) or
<code>ACEStart</code> (see <a href="CHAP006.htm#SSEC001.1">ACEStart</a>), that may be applied, is automatically
invoked.

Since a user will sometimes have options in the form of a record
(e.g. via <code>GetACEOptions</code>), we provide an alternative to the
behind-the-colon syntax, in a manner .like <code>PushOptions</code>, for the
passing of options via <code>SetACEOptions</code>:

<a name = "SSEC005.9"></a>
<li><code>SetACEOptions( </code><var>i</var><code>, </code><var>optionsRec</var><code> ) F</code>
<li><code>SetACEOptions( </code><var>optionsRec</var><code> ) F</code>

In this form, the record <var>optionsRec</var> is used to update the current
options of the <var>i</var>th (or default) process started by <code>ACEStart</code>. Note
that since <var>optionsRec</var> is a record each field must have an assigned
value; in particular, no-value ACE options should be assigned the
value <code>true</code> (see Section <a href="CHAP004.htm#SECT006">Interpretation of ACE Options</a>). Please
don't mix these two forms of SetACEOptions with the previous two
forms; i.e. do not pass both a record argument and options, since
this will lead to options appearing in the wrong order; if you want to
do this, make two separate calls to <code>SetACEOptions</code>, e.g. let's say
you have a process like that started by:

<pre>
gap> ACEExample("A5", ACEStart);

</pre>

then the following demonstrates both usages of <code>SetACEOptions</code>:

<pre>
gap> SetACEOptions( rec(echo := 2) );
gap> SetACEOptions( : hlt);

</pre>

Each of the three commands above generates output; for brevity it has
not been included.

Notes:

<a name = "I2"></a>

When <code>ACECosetTableFromGensAndRels</code> enters a <code>break</code>-loop
(see <a href="CHAP001.htm#SSEC002.1">ACECosetTable</a>), local versions of the second form of each of
<code>DisplayACEOptions</code> and <code>SetACEOptions</code> become available. (Even though
the names are similar and their function is analogous they are in fact
different functions.)

<a name = "SSEC005.10"></a>
<li><code>ACEParameters( </code><var>i</var><code> ) F</code>
<li><code>ACEParameters() F</code>

return a record of the current values of the ACE Parameter Options
(see <a href="CHAP004.htm#SSEC012.1">ACEParameterOptions</a>) of the <var>i</var>th (or default) process started
by <code>ACEStart</code>, according to ACE. Please note that some options may
be reported with incorrect values if they have been changed recently
without following up with one of the modes <code>ACEContinue</code>, <code>ACERedo</code> or
<code>ACEStart</code>. Together the commands <code>ACEGroupGenerators</code>, <code>ACERelators</code>,
<code>ACESubgroupGenerators</code> and <code>ACEParameters</code> give the equivalent GAP
information that is obtained in ACE with <code>sr := 1</code> (see <a href="CHAP00D.htm#SSEC005.7">option sr</a>), which is the ``Run Parameters'' block obtained in the messaging
output (observable when the <code>InfoLevel</code> of <code>InfoACE</code> is set to at
least 3), when <code>messages</code> (see <a href="CHAP004.htm#SSEC018.1">option messages</a>) is set a non-zero
value.

Notes:
One use for this function might be to determine the options required
to replicate a previous run, but be sure that, if this is your
purpose, any recent change in the parameter option values has been
followed by an invocation of one of <code>ACEContinue</code> (see <a href="CHAP006.htm#SSEC002.2">ACEContinue</a>),
<code>ACERedo</code> (see <a href="CHAP006.htm#SSEC002.3">ACERedo</a>) or <code>ACEStart</code> (see <a href="CHAP006.htm#SSEC001.1">ACEStart</a>).

As a side-effect, for ACE process <var>i</var>, any of the fields of
<code>ACEData.io[</code><var>i</var><code>].args</code> or <code>ACEData.io[</code><var>i</var><code>].acegens</code> that are unset,
are set.

<a name = "SSEC005.11"></a>
<li><code>IsCompleteACECosetTable( </code><var>i</var><code> ) F</code>
<li><code>IsCompleteACECosetTable() F</code>

return, for the <var>i</var>th (or default) process started by <code>ACEStart</code>,
<code>true</code> if ACE's current coset table is complete, or false
otherwise.

Note:
The completeness of the coset table of the <var>i</var>th interactive ACE
process is determined by checking whether
<code>ACEData.io[</code><var>i</var><code>].stats.index</code> is positive; a value of zero indicates
the last enumeration failed to complete. The record
<code>ACEData.io[</code><var>i</var><code>].stats</code> is what is returned by <code>ACEStats(</code><var>i</var><code>)</code>
(see <a href="CHAP001.htm#SSEC003.1">ACEStats</a>).

<a name = "SSEC005.12"></a>
<li><code>ACEDisplayCosetTable( </code><var>i</var><code> ) F</code>
<li><code>ACEDisplayCosetTable() F</code>
<li><code>ACEDisplayCosetTable( </code><var>i</var><code>, [</code><var>val</var><code>] ) F</code>
<li><code>ACEDisplayCosetTable( [</code><var>val</var><code>] ) F</code>
<li><code>ACEDisplayCosetTable( </code><var>i</var><code>, [</code><var>val</var><code>, </code><var>last</var><code>] ) F</code>
<li><code>ACEDisplayCosetTable( [</code><var>val</var><code>, </code><var>last</var><code>] ) F</code>
<li><code>ACEDisplayCosetTable( </code><var>i</var><code>, [</code><var>val</var><code>, </code><var>last</var><code>, </code><var>by</var><code>] ) F</code>
<li><code>ACEDisplayCosetTable( [</code><var>val</var><code>, </code><var>last</var><code>, </code><var>by</var><code>] ) F</code>

compact and display the (possibly incomplete) coset table of the <var>i</var>th
(or default) process started by <code>ACEStart</code>; <var>val</var> must be an integer,
and <var>last</var> and <var>by</var> must be positive integers. In the first two forms
of the command, the entire coset table is displayed, without orders or
coset representatives. In the third and fourth forms, the absolute
value of <var>val</var> is taken to be the last line of the table to be
displayed (and 1 is taken to be the first); in the fifth and sixth
forms, <code>|</code><var>val</var><code>|</code> is taken to be the first line of the table to be
displayed, and <var>last</var> is taken to be the number of the last line to be
displayed. In the last two forms, the table is displayed from line
<code>|</code><var>val</var><code>|</code> to line <var>last</var> in steps of <var>by</var>. If <var>val</var> is negative, then
the orders modulo the subgroup (if available) and coset
representatives are displayed also.

Note:
The coset table displayed will normally only be <code>lenlex</code> standardised
if the call to <code>ACEDisplayCosetTable</code> is preceded by
<code>ACEStandardCosetNumbering</code> (see <a href="CHAP006.htm#SSEC007.2">ACEStandardCosetNumbering</a>). The
options <code>lenlex</code> (see <a href="CHAP004.htm#SSEC011.4">option lenlex</a>) and <code>semilenlex</code> (see <a href="CHAP004.htm#SSEC011.5">option semilenlex</a>) are only executed by <code>ACECosetTable</code>
(see <a href="CHAP001.htm#SSEC002.1">ACECosetTable</a>). The ACE binary does not provide <code>semilenlex</code>
standardisation, and hence <code>ACEDisplayCosetTable</code> will never display a
<code>semilenlex</code> standard coset table.

<a name = "SSEC005.13"></a>
<li><code>ACECosetRepresentative( </code><var>i</var><code>, </code><var>n</var><code> ) F</code>
<li><code>ACECosetRepresentative( </code><var>n</var><code> ) F</code>

return, for the <var>i</var>th (or default) process started by <code>ACEStart</code>, the
coset representative of coset <var>n</var> of the current coset table held by
ACE, where <var>n</var> must be a positive integer.

<a name = "SSEC005.14"></a>
<li><code>ACECosetRepresentatives( </code><var>i</var><code> ) F</code>
<li><code>ACECosetRepresentatives() F</code>

return, for the <var>i</var>th (or default) process started by <code>ACEStart</code>, the
--> --------------------

--> maximum size reached

--> --------------------

quality100%

¤ Dauer der Verarbeitung: 0.69 Sekunden (vorverarbeitet) ¤

*© Formatika GbR, Deutschland

Wurzel

Suchen

Beweissystem der NASA

Beweissystem Isabelle

NIST Cobol Testsuite

Cephes Mathematical Library

Wiener Entwicklungsmethode

Haftungshinweis

Die Informationen auf dieser Webseite wurden nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit, noch Qualität der bereit gestellten Informationen zugesichert.

Bemerkung:

Die farbliche Syntaxdarstellung ist noch experimentell.