Quelle CHAP001.htm Sprache: HTML

products/Sources/formale Sprachen/GAP/pkg/ace/htm/CHAP001.htm

<html><head><title>[ACE] 1 The ACE Package</title></head>
<body text="#000000" bgcolor="#ffffff">
[<a href = "chapters.htm">Up</a>] [<a href ="CHAP002.htm">Next</a>] [<a href = "theindex.htm">Index</a>]
<h1>1 The ACE Package</h1>

<H3>Sections</H3>
<oL>
<li> <A HREF="CHAP001.htm#SECT001">Using ACE as a Default for Coset Enumerations</a>
<li> <A HREF="CHAP001.htm#SECT002">Using ACE Directly to Generate a Coset Table</a>
<li> <A HREF="CHAP001.htm#SECT003">Using ACE Directly to Test whether a Coset Enumeration Terminates</a>
<li> <A HREF="CHAP001.htm#SECT004">Writing ACE Standalone Input Files to Generate a Coset Table</a>
<li> <A HREF="CHAP001.htm#SECT005">Using ACE Interactively</a>
<li> <A HREF="CHAP001.htm#SECT006">Accessing ACE Examples with ACEExample and ACEReadResearchExample</a>
<li> <A HREF="CHAP001.htm#SECT007">General Warnings regarding the Use of Options</a>
<li> <A HREF="CHAP001.htm#SECT008">The ACEData Record</a>
<li> <A HREF="CHAP001.htm#SECT009">Setting the Verbosity of ACE via Info and InfoACE</a>
<li> <A HREF="CHAP001.htm#SECT010">Acknowledgements</a>
<li> <A HREF="CHAP001.htm#SECT011">Changes from earlier versions</a>
</ol>

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

The ``Advanced Coset Enumerator'' ACE:

<pre>
ACE coset enumerator (C) 1995-2001 by George Havas and Colin Ramsay
</pre>
<a href="http://staff.itee.uq.edu.au/havas">http://staff.itee.uq.edu.au/havas</a>

can be called from within GAP through an interface, written by
Alexander Hulpke and Greg Gamble, which is described in this manual.

The interface links to an external binary and therefore is only usable
under UNIX (see Section <a href="CHAP002.htm#SECT001">Installing the ACE Package</a> for how to
install ACE). It will not work on Windows.
The current version requires at least GAP 4.4.

<ul>

<li> one may supplant the usual GAP coset enumerator (see
Section <a href="CHAP001.htm#SECT001">Using ACE as a Default for Coset Enumerations</a>),

<li> one may generate a coset table using ACE without
redefining the usual GAP coset enumerator (see Section <a href="CHAP001.htm#SECT002">Using ACE Directly to Generate a Coset Table</a>),

<li> one may simply test whether a coset enumeration will
terminate (see Section <a href="CHAP001.htm#SECT003">Using ACE Directly to Test whether a Coset Enumeration Terminates</a>),

<li> one may use GAP to write a script for the ACE
standalone (see Section <a href="CHAP001.htm#SECT004">Writing ACE Standalone Input Files to Generate a Coset Table</a>), and

<li> one may interact with the ACE standalone from within
GAP (see Section <a href="CHAP001.htm#SECT005">Using ACE Interactively</a>). Among other things,
the interactive ACE interface functions (described in
Chapter <a href="CHAP006.htm">Functions for Using ACE Interactively</a>) enable the user to
search for subgroups of a group (see the note of Section <a href="CHAP001.htm#SECT005">Using ACE Interactively</a>).

</ul>

Each of these ways gives the user access to a welter of options, which
are discussed in full in Chapters <a href="CHAP004.htm">Options for ACE</a> and <a href="CHAP005.htm">Strategy Options for ACE</a>. Yet more options are provided in Appendix <a href="CHAP00D.htm">Other ACE Options</a>, but please take note of the Appendix's introductory
paragraph. Check out Appendix <a href="CHAP00B.htm">Examples</a> for numerous examples of the
ACE commands.

Note: Some care needs to be taken with options; be sure to read
Section <a href="CHAP001.htm#SECT007">General Warnings regarding the Use of Options</a> and the
introductory sections of Chapter <a href="CHAP004.htm">Options for ACE</a> for some warnings
regarding them and a general discussion of their use, before using any
of the functions provided by this interface to the ACE binary.


<h2><a name="SECT001">1.1 Using ACE as a Default for Coset Enumerations</a></h2>

After loading ACE (see Section <a href="CHAP002.htm#SECT002">Loading the ACE Package</a>), if you
want to use the ACE coset enumerator as a default for all coset
enumerations done by GAP (which may also get called indirectly),
you can achieve this by setting the global variable <code>TCENUM</code> to
<code>ACETCENUM</code>.

<pre>
gap> TCENUM:=ACETCENUM;;

</pre>

This sets the function <code>CosetTableFromGensAndRels</code> (see
Section <a href="../../../doc/ref/chap47.html#X7BD0CEBA7B225416">Coset Tables and Coset Enumeration</a> in the GAP
Reference Manual) to be the function <code>ACECosetTableFromGensAndRels</code>
(described in Section <a href="CHAP001.htm#SECT002">Using ACE Directly to Generate a Coset Table</a>),
which then can be called with all the options defined for the ACE
interface, not just the options <code>max</code> and <code>silent</code>. If <code>TCENUM</code> is set
to <code>ACETCENUM</code> without any further action, the <code>default</code> strategy
(option) of the ACE enumerator will be used (see Chapter <a href="CHAP005.htm">Strategy Options for ACE</a>). This and other options can be modified in the ways
described in Chapter <a href="CHAP004.htm">Options for ACE</a>. For instance,

<pre>
gap> FactorCosetAction(G,H : workspace:=10^9);

</pre>

will result in ACE called with workspace of size 109, instead of
the default value.

You can switch back to the coset enumerator built into the GAP
library by assigning <code>TCENUM</code> to <code>GAPTCENUM</code>.

<pre>
gap> TCENUM:=GAPTCENUM;;

</pre>


<h2><a name="SECT002">1.2 Using ACE Directly to Generate a Coset Table</a></h2>

If, on the other hand you do not want to set up ACE globally for
your coset enumerations, you may call the ACE interface directly,
which will allow you to decide for yourself, for each such call, which
options you want to use for running ACE. Please note the warnings
regarding options in Section <a href="CHAP001.htm#SECT007">General Warnings regarding the Use of Options</a>. The functions discussed in this and the following section
(<code>ACECosetTableFromGensAndRels</code> and <code>ACEStats</code>) are non-interactive,
i.e. by their use, a file with your input data in ACE readable
format will be handed to ACE and you will get the answer back in
GAP format. At that moment however the ACE job is terminated,
that is, you cannot send any further questions or requests about the
result of that job to ACE. For an interactive use of ACE from
GAP see Section <a href="CHAP001.htm#SECT005">Using ACE Interactively</a> and Chapter <a href="CHAP006.htm">Functions for Using ACE Interactively</a>.

Using the ACE interface directly to generate a coset table is done
by either of

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

<a name = "SSEC002.1"></a>
<li><code>ACECosetTableFromGensAndRels( </code><var>fgens</var><code>, </code><var>rels</var><code>, </code><var>sgens</var><code> [: </code><var>options</var><code>] ) F</code>
<a name = "SSEC002.1"></a>
<li><code>ACECosetTable( </code><var>fgens</var><code>, </code><var>rels</var><code>, </code><var>sgens</var><code> [: </code><var>options</var><code>] ) F</code>

Here <var>fgens</var> is a list of free generators, <var>rels</var> a list of words in
these generators giving relators for a finitely presented group, and
<var>sgens</var> the list of subgroup generators, again expressed as words in
the free generators. All these are given in the standard GAP format
(see Chapter <a href="../../../doc/ref/chap47.html#X7AA982637E90B35A">Finitely Presented Groups</a> of the GAP Reference
Manual). Note that the 3-argument form of <code>ACECosetTable</code> described
here is merely a synonym for <code>ACECosetTableFromGensAndRels</code>, and that
<code>ACECosetTable</code> may be called in a different way in an interactive
ACE session (see Sections <a href="CHAP001.htm#SECT005">Using ACE Interactively</a>
and <a href="CHAP006.htm#SSEC006.1">ACECosetTable!interactive</a>).

Behind the colon any selection of the options available for the
interface (see Chapters <a href="CHAP004.htm">Options for ACE</a> and <a href="CHAP005.htm">Strategy Options for ACE</a>) can be given, separated by commas like record components. These
can be used e.g. to preset limits of space and time to be used, to
modify input and output and to modify the enumeration procedure. Note
that strategies are simply special options that set a number of the
options, detailed in Chapter <a href="CHAP004.htm">Options for ACE</a>, all at once.

Please see Section <a href="CHAP001.htm#SECT007">General Warnings regarding the Use of Options</a> for
a discussion regarding global and local passing of options, and the
non-orthogonal nature of ACE's options.

Each of <code>ACECosetTableFromGensAndRels</code> and <code>ACECosetTable</code> calls the
ACE binary and, if successful, returns a standard coset table, as a
GAP list of lists. At the time of writing, two coset table
standardisations schemes were possible: <code>lenlex</code> and <code>semilenlex</code> (see
Section <a href="CHAP003.htm#SECT004">Coset Table Standardisation Schemes</a>). The user may control
which standardisation scheme is used by selecting either the <code>lenlex</code>
(see <a href="CHAP004.htm#SSEC011.4">option lenlex</a>) or <code>semilenlex</code> (see <a href="CHAP004.htm#SSEC011.5">option semilenlex</a>)
option; otherwise the table is standardised according to GAP's
the value of <code>CosetTableStandard</code> (which by default is <code>lenlex</code>).
We provide <code>IsACEStandardCosetTable</code> (see <a href="CHAP001.htm#SSEC002.2">IsACEStandardCosetTable</a>)
to determine whether a table (list of lists) is standard relative to
GAP's default standardisation scheme, or with the use of options
(e.g. <code>lenlex</code> or <code>semilenlex</code>) to another standardisation scheme.

If the determination of a coset table is unsuccessful, then one of the
following occurs:

<ul>

<li> with the <code>incomplete</code> option (see <a href="CHAP004.htm#SSEC011.6">option incomplete</a>) an
incomplete coset table is returned (as a list of lists), with zeros in
positions where valid coset numbers could not be determined; or

<li> with the <code>silent</code> option (see <a href="CHAP004.htm#SSEC011.3">option silent</a>), <code>fail</code> is
returned; or

<li> a <code>break</code>-loop is entered. This last possibility is
discussed in detail via the example that follows.

</ul>

The example given below is the call for a presentation of the
Fibonacci group F(2,7) for which we shall discuss the impact of
various options in Section <a href="CHAP00B.htm#SECT004">Fun with ACEExample</a>. Observe that in the
example, no options are passed, which means that ACE uses the
<code>default</code> strategy (see Chapter <a href="CHAP005.htm">Strategy Options for ACE</a>).

<pre>
gap> F:= FreeGroup( "a", "b", "c", "d", "e", "x", "y");;
gap> a:= F.1;; b:= F.2;; c:= F.3;; d:= F.4;; e:= F.5;; x:= F.6;; y:= F.7;;
gap> fgens:= [a, b, c, d, e, x, y];;
gap> rels:= [ a*b*c^-1, b*c*d^-1, c*d*e^-1, d*e*x^-1,
> e*x*y^-1, x*y*a^-1, y*a*b^-1];;
gap> ACECosetTable(fgens, rels, [c]);;

</pre>

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

In computing the coset table, <code>ACECosetTableFromGensAndRels</code> must
first do a coset enumeration (which is where ACE comes in!). If the
coset enumeration does not finish in the preset limits a <code>break</code>-loop
is entered, unless the <code>incomplete</code> (see <a href="CHAP004.htm#SSEC011.6">option incomplete</a>) or
<code>silent</code> (see <a href="CHAP004.htm#SSEC011.3">option silent</a>) options is set. In the event that a
<code>break</code>-loop is entered, don't despair or be frightened by the word
<code>Error</code>; by tweaking ACE's options via the SetACEOptions function
that becomes available in the <code>break</code>-loop and then typing <code>return;</code>
it may be possible to help ACE complete the coset enumeration (and
hence successfully compute the coset table); if not, you will end up
in the <code>break</code>-loop again, and you can have another go (or <code>quit;</code> if
you've had enough). The SetACEOptions function is a no-argument
function; it's there purely to pass options (which, of course, are
listed behind a colon (<code>:</code>) with record components syntax). Let's
continue the Fibonacci example above, redoing the last command but
with the option <code>max := 2</code> (see <a href="CHAP004.htm#SSEC017.6">option max</a>), so that the coset
enumeration has only two coset numbers to play with and hence is bound
to fail to complete, putting us in a <code>break</code>-loop.

<a name = "I3"></a>

<pre>
gap> ACECosetTable(fgens, rels, [c] : max := 2);
Error, no coset table ...
the `ACE' coset enumeration failed with the result:
OVERFLOW (a=2 r=1 h=1 n=3; l=5 c=0.00; m=2 t=2)
called from
<function "ACECosetTable">( <arguments> ) called from read-eval-loop
Entering break read-eval-print loop ...
try relaxing any restrictive options
e.g. try the `hard' strategy or increasing `workspace'
type: '?strategy options' for info on strategies
type: '?options for ACE' for info on options
type: 'DisplayACEOptions();' to see current ACE options;
type: 'SetACEOptions(:<option1> := <value1>, ...);'
to set <option1> to <value1> etc.
(i.e. pass options after the ':' in the usual way)
... and then, type: 'return;' to continue.
Otherwise, type: 'quit;' to quit to outer loop.
brk> SetACEOptions(: max := 0);
brk> return;
[ [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ],
 [ 1 ], [ 1 ], [ 1 ], [ 1 ] ]

</pre>

Observe how the lines after the ``<code>Entering break read-eval-print
loop</code>'' announcement tell you exactly what to do. At the
<code>break</code>-loop prompt <code>brk></code> we relaxed all
restrictions on <code>max</code> (by re-setting it to 0) and typed <code>return;</code> to
leave the <code>break</code>-loop. The coset enumeration was then successful,
allowing the computation of what turned out to be a trivial coset
table. Despite the fact that the eventual coset table only has one
line (i.e. there is exactly one coset number) ACE did need to
define more than 2 coset numbers. To find out just how many were
required before the final collapse, let's set the InfoLevel of
<code>InfoACE</code> (see <a href="CHAP001.htm#SSEC009.1">InfoACE</a>) to 2, so that the ACE enumeration
result is printed.

<pre>
gap> SetInfoLevel(InfoACE, 2);
gap> ACECosetTable(fgens, rels, [c]);
#I INDEX = 1 (a=1 r=2 h=2 n=2; l=6 c=0.00; m=2049 t=3127)
[ [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ],
 [ 1 ], [ 1 ], [ 1 ], [ 1 ] ]

</pre>

The enumeration result line is the <code>Info</code> line beginning ``<code>#I </code>''.
Appendix <a href="CHAP00A.htm">The Meanings of ACE's Output Messages explains how to
interpret such output messages from ACE. In particular, it explains
that <code>t=3127</code> tells us that a <code>t</code>otal number of 3127 coset numbers
needed to be defined before the final collapse to 1 coset number.
Using some of the many options that ACE provides, one may achieve
this result more efficiently, e.g. with the <code>purec</code> strategy
(see <a href="CHAP005.htm#SSEC001.6">option purec</a>):

<pre>
gap> ACECosetTable(fgens, rels, [c] : purec);
#I INDEX = 1 (a=1 r=2 h=2 n=2; l=4 c=0.00; m=332 t=332)
[ [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ],
 [ 1 ], [ 1 ], [ 1 ], [ 1 ] ]

</pre>

ACE needs to define a <code>t</code>otal number of only (relatively-speaking)
332 coset numbers before the final collapse to 1 coset number.

Notes:
To initiate the coset enumeration, the <code>start</code> option (see <a href="CHAP00D.htm#SSEC003.2">option start</a>) is quietly inserted after the user's supplied options, unless
the user herself supplies one of the enumeration-invoking options,
which are: <code>start</code>, or one of its synonyms, <code>aep</code> (see <a href="CHAP00D.htm#SSEC001.1">option aep</a>)
or <code>rep</code> (see <a href="CHAP00D.htm#SSEC001.2">option rep</a>).

When a user calls <code>ACECosetTable</code> with the <code>lenlex</code> option
(see <a href="CHAP004.htm#SSEC011.4">option lenlex</a>), occasionally it is necessary to enforce
<code>asis</code>=1 (see <a href="CHAP004.htm#SSEC013.1">option asis</a>), which may be counter to the desires
of the user. The occasions where this action is necessary are
precisely those for which, for the arguments <var>gens</var> and <var>rels</var> of
<code>ACECosetTable</code>, <code>IsACEGeneratorsInPreferredOrder</code> would return
<code>false</code>.

The non-interactive <code>ACECosetTable</code> and <code>ACECosetTableFromGensAndRels</code>
now use an iostream to communicate with the ACE binary in order to
avoid filling up a temporary directory with an incomplete coset table
in the case where an enumeration overflows. This is generally
advantageous. However, on some systems, it may not be advisable to
repeatedly call <code>ACECosetTable</code> or <code>ACECosetTableFromGensAndRels</code>
(e.g. in a loop), since one may run out of the pseudo ttys used for
iostreams. If you encounter this problem, consider using an adaptation
of the usage of the interactive forms of <code>ACECosetTable</code> and
<code>ACEStats</code> (see <a href="CHAP006.htm#SSEC006.1">ACECosetTable!interactive</a>
and <a href="CHAP006.htm#SSEC006.2">ACEStats!interactive</a>), together with <code>ACEStart</code> initialisation
steps, that is sketched in the schema below. For the following code,
it is imagined the scenario is one of looping over several
possibilities of <var>fgens</var>, <var>rels</var> and <var>sgens</var>; the two special forms of
<code>ACEStart</code> used, allow one to continually re-use a single interactive
ACE process (i.e. only one iostream is used).

<code># start the interactive ACE process with no group information</code>
 <code>procId := ACEStart(0);</code>
 <code>while </code><var>expr</var><code> do</code>
 <code> fgens := ...; rels := ...; sgens := ...;</code>
 <code> ACEStart(procId, fgens, rels, sgens : </code><var>options</var><code>);</code>
 <code> if ACEStats(procId).index > 0 then</code>
 <code> table := ACECosetTable(procId);</code>
 <code> ...</code>
 <code> fi;</code>
 <code>od;</code>

For an already calculated coset table, we provide the following
function to determine whether or not it has been standardised.

<a name = "SSEC002.2"></a>
<li><code>IsACEStandardCosetTable( </code><var>table</var><code> [: </code><var>option</var><code>] ) F</code>

returns <code>true</code> if <var>table</var> (a list of lists of integers) is standard
according to GAP's default or the option (either lenlex or
<code>semilenlex</code>) standardisation scheme, or <code>false</code> otherwise. See
Section <a href="CHAP003.htm#SECT004">Coset Table Standardisation Schemes</a> for a detailed
discussion of the <code>lenlex</code> and <code>semilenlex</code> standardisation schemes.

Note:
Essentially, <code>IsACEStandardCosetTable</code> extends the GAP function
<code>IsStandardized</code>.

<a name = "I4"></a>

Users who wish their coset tables to use <code>ACECosetTable</code> with the
<code>lenlex</code> (see <a href="CHAP004.htm#SSEC011.4">option lenlex</a>) option, which causes
<code>lenlex</code> standardisation to occur at the ACE (rather than GAP)
level, should be aquainted with the following function.

<a name = "I5"></a>

<a name = "SSEC002.3"></a>
<li><code>IsACEGeneratorsInPreferredOrder( </code><var>gens</var><code>, </code><var>rels</var><code> ) F</code>

returns <code>true</code> if <var>gens</var>, a list of free group generators, are in an
order which will not be changed by ACE, for the group with
presentation 〈gens | rels 〉, where <var>rels</var> is a
list of relators (i.e. words in the generators <var>gens</var>).
<code>IsACEGeneratorsInPreferredOrder</code> may also be called in a different
way for interactive ACE processes
(see <a href="CHAP006.htm#SSEC006.3">IsACEGeneratorsInPreferredOrder!interactive</a>).

For a presentation with more than one generator, the first generator
of which is an involution and the second is not, ACE prefers to
switch the first two generators. <code>IsACEGeneratorsInPreferredOrder</code>
returns <code>true</code> if the order of the generators <var>gens</var> would not be
changed within ACE and <code>false</code>, otherwise. (Technically, by
``involution'' above, we really mean ``a generator <code>x</code> for which there
is a relator in <var>rels</var> of form <code>x*x</code> or <code>x^2</code>''. Such a generator may,
of course, turn out to actually be the identity.)

Guru Notes:
If <code>IsACEGeneratorsInPreferredOrder(</code><var>gens</var><code>, </code><var>rels</var><code>)</code> would return
<code>false</code>, it is possible to enforce a user's order of the generators
within ACE, by setting the option <code>asis</code> (see <a href="CHAP004.htm#SSEC013.1">option asis</a>) to 1
and, by passing the relator that determines that <code></code><var>gens</var><code>[1]</code> (which we
will assume is <code>x</code>) has order at most 2, as: <code>x*x</code> (rather than
<code>x^2</code>). Behind the scenes this is precisely what is done, if
necessary, when <code>ACECosetTable</code> is called with the <code>lenlex</code> option.

The user may avoid all the technicalities by either not using the
<code>lenlex</code> option (and allowing GAP to take care of the <code>lenlex</code>
standardisation), or by swapping the first two generators in those
cases where <code>IsACEGeneratorsInPreferredOrder(</code><var>gens</var><code>, </code><var>rels</var><code>)</code> would
return <code>false</code>.


<h2><a name="SECT003">1.3 Using ACE Directly to Test whether a Coset Enumeration Terminates</a></h2>

If you only want to test, whether a coset enumeration terminates, and
don't want to transfer the whole coset table to GAP, you can call

<a name = "I6"></a>

<a name = "SSEC003.1"></a>
<li><code>ACEStats( </code><var>fgens</var><code>, </code><var>rels</var><code>, </code><var>sgens</var><code> [: </code><var>options</var><code>] ) F</code>

which calls ACE non-interactively to do the coset enumeration, the
result of which is parsed and returned as a GAP record with fields


<dl compact>

<dt> <code>index</code> <dd>the index of the subgroup 〈sgens 〉 in
〈fgens | rels 〉, or 0 if the enumeration does
not succeed;

<dt> <code>cputime</code> <dd>the total CPU time used as an integer number of
<code>cputimeUnits</code> (the next field);

<dt> <code>cputimeUnits</code> <dd>the units of the <code>cputime</code> field, e.g. <code>"10^-2
seconds";

<a name = "I7"></a>

<dt> <code>activecosets</code> <dd>the number of currently active (i.e. alive)
coset numbers (see Section <a href="CHAP003.htm#SECT005">Coset Statistics Terminology</a>);

<a name = "I8"></a>

<dt> <code>maxcosets</code> <dd>the maximum number of alive coset numbers at any
one time in the enumeration (see Section <a href="CHAP003.htm#SECT005">Coset Statistics Terminology</a>); and

<a name = "I9"></a>

<dt> <code>totcosets</code> <dd>the total number of coset numbers that were
defined in the enumeration (see Section <a href="CHAP003.htm#SECT005">Coset Statistics Terminology</a>).

</dl>

Options (see Chapters <a href="CHAP004.htm">Options for ACE</a> and <a href="CHAP005.htm">Strategy Options for ACE</a>) are used in exactly the same way as for
<code>ACECosetTableFromGensAndRels</code>, discussed in the previous section; and
the same warnings alluded to previously, regarding options (see
Section <a href="CHAP001.htm#SECT007">General Warnings regarding the Use of Options</a>), apply.

Notes:
To initiate the coset enumeration, the <code>start</code> option (see <a href="CHAP00D.htm#SSEC003.2">option start</a>) is quietly inserted after the user's supplied options, unless
the user herself supplies one of the enumeration-invoking options,
which are: <code>start</code>, or one of its synonyms, <code>aep</code> (see <a href="CHAP00D.htm#SSEC001.1">option aep</a>)
or <code>rep</code> (see <a href="CHAP00D.htm#SSEC001.2">option rep</a>).

The fields of the <code>ACEStats</code> record are determined by parsing a
``results message'' (see Appendix <a href="CHAP00A.htm">The Meanings of ACE's Output Messages) from ACE.

<code>ACEStats</code> may also be called in a different way in an interactive
ACE session (see <a href="CHAP006.htm#SSEC006.2">ACEStats!interactive</a>).


<h2><a name="SECT004">1.4 Writing ACE Standalone Input Files to Generate a Coset Table</a></h2>

If you want to use ACE as a standalone with its own syntax, you can
write an ACE standalone input file by calling <code>ACECosetTable</code> with
three arguments (see <a href="CHAP001.htm#SSEC002.1">ACECosetTableFromGensAndRels</a>) and the option
<code>aceinfile := </code><var>filename</var><code></code> (see <a href="CHAP004.htm#SSEC011.7">option aceinfile</a>). This will keep the
input file for the ACE standalone produced by the GAP interface
under the file name <var>filename</var> (and just return) so that you can
perform interactive work in the standalone.


<h2><a name="SECT005">1.5 Using ACE Interactively</a></h2>

An interactive ACE process is initiated with the command

<a name = "SSEC005.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>

whose arguments and options are exactly as for
<code>ACECosetTableFromGensAndRels</code> and <code>ACEStats</code>, as discussed in
Sections <a href="CHAP001.htm#SECT002">Using ACE Directly to Generate a Coset Table</a> and <a href="CHAP001.htm#SECT003">Using ACE Directly to Test whether a Coset Enumeration Terminates</a>. The usual
warnings regarding options apply (see Section <a href="CHAP001.htm#SECT007">General Warnings regarding the Use of Options</a>). <code>ACEStart</code> has a number of other forms
(see <a href="CHAP006.htm#SSEC001.1">ACEStart!details</a>).

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

An interactive ACE process is terminated with the command

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

where <var>i</var> is the integer returned by <code>ACEStart</code> when the process was
begun. <code>ACEQuit</code> may also be called with no arguments
(see <a href="CHAP006.htm#SSEC001.2">ACEQuit!details</a>).

We discuss each of these commands, as well as the range of functions
which enable one to access features of the ACE standalone not
available non-interactively, in depth, in Chapter <a href="CHAP006.htm">Functions for Using ACE interactively</a>.

Note:

<a name = "I10"></a>

ACE not only allows one to do a coset enumeration of a group by a
given (and then fixed) subgroup but it also allows one to search for
subgroups by starting from a given one (possibly the trivial subgroup)
and then augmenting it by adding new subgroup generators either
explicitly via <code>ACEAddSubgroupGenerators</code>
(see <a href="CHAP006.htm#SSEC007.4">ACEAddSubgroupGenerators</a>) or implicitly by introducing
coincidences (see <code>ACECosetCoincidence</code>: <a href="CHAP006.htm#SSEC007.7">ACECosetCoincidence</a>, or
<code>ACERandomCoincidences</code>: <a href="CHAP006.htm#SSEC007.8">ACERandomCoincidences</a>); or one can find
smaller subgroups by deleting subgroup generators via
<code>ACEDeleteSubgroupGenerators</code> (see <a href="CHAP006.htm#SSEC007.6">ACEDeleteSubgroupGenerators</a>).


<h2><a name="SECT006">1.6 Accessing ACE Examples with ACEExample and ACEReadResearchExample</a></h2>

There are a number of examples available in the <code>examples</code> directory,
which may be accessed via

<a name = "SSEC006.1"></a>
<li><code>ACEExample() F</code>
<li><code>ACEExample( </code><var>examplename</var><code> [:</code><var>options</var><code>] ) F</code>
<li><code>ACEExample( </code><var>examplename</var><code>, </code><var>ACEfunc</var><code> [:</code><var>options</var><code>] ) F</code>

where <var>examplename</var> is a string, the name of an example (and
corresponding file in the <code>examples</code> directory); and <var>ACEfunc</var> is the
ACE function with which the example is to be executed.

If <code>ACEExample</code> is called with no arguments, or with the argument:
<code>"index"</code> (meant in the sense of ``list''), or with a non-existent
example name, a list of available examples is displayed. See
Section <a href="CHAP00B.htm#SECT004">Fun with ACEExample</a> where the list is displayed.

By default, examples are executed via <code>ACEStats</code>. However, if
<code>ACEExample</code> is called with a second argument (choose from the (other)
alternatives: <code>ACECosetTableFromGensAndRels</code> (or, equivalently
<code>ACECosetTable</code>), or <code>ACEStart</code>), the example is executed using that
function, instead. Note that, whereas the first argument appears in
double quotes (since it's a string), the second argument does not
(since it's a function); e.g. to execute example "A5" with function
<code>ACECosetTable</code>, one would type: <code>ACEExample("A5", ACECosetTable);</code>.

<code>ACEExample</code> also accepts user options, which may be passed either
globally (i.e. by using <code>PushOptions</code> to push them onto the
<code>OptionsStack</code>) or locally behind a colon after the <code>ACEExample</code>
arguments, and they are passed to <code>ACEStats</code> or <var>ACEfunc</var> as if they
were appended to the existing options of <var>examplename</var>; in this way,
the user may over-ride any or all of the options of <var>examplename</var>.
This is done by passing an option <code>aceexampleoptions</code> (see <a href="CHAP004.htm#SSEC011.15">option aceexampleoptions</a>), which sets up a mechanism to reverse the usual
order in which options of recursively called functions are pushed onto
the <code>OptionsStack</code>. The option <code>aceexampleoptions</code> is not a user
option; it is intended only for internal use by <code>ACEExample</code>, for
the above purpose. In the portion of the output due to the <code>echo</code>
option, if one has passed options to <code>ACEExample</code>, one will see
<code>aceexampleoptions</code> listed first and the result of the interaction of
<var>examplename</var>'s options and the additional options.

Consider the example <code>"A5"</code>. The effect of running

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

</pre>

is essentially equivalent to executing:

<pre>
gap> file := Filename(DirectoriesPackageLibrary("ace", "examples"), "A5");;
gap> ACEfunc := ACEStart;;
gap> ReadAsFunction(file)();

</pre>

except that some internal ``magic'' of <code>ACEExample</code> edits the example
file and displays equivalent commands a user ``would'' execute. If the
user has passed options to <code>ACEExample</code> these appear in a
``<code># User Options</code>'' block after the original options of the example
in the <code>Info</code> portion of the output. By comparing with the portion of
the output from the <code>echo</code> option (unless the user has over-ridden the
<code>echo</code> option), the user may directly observe any over-riding effects
of user-passed options.

Please see Section <a href="CHAP00B.htm#SECT004">Fun with ACEExample</a> for some sample interactions
with <code>ACEExample</code>.

Notes

Most examples use the <code>mess</code> ( = <tt>messages</tt>) option. To see the
effect of this, it is recommended to do: <code>SetInfoLevel(InfoACE, 3);</code>
before calling <code>ACEExample</code>, with an example.

The coset table output from <code>ACEExample</code>, when called with many of the
examples and with the ACE function <code>ACECosetTableFromGensAndRels</code>
is often quite long. Recall that the output may be suppressed by
following the (<code>ACEExample</code>) command with a double semicolon (<code>;;</code>).

Also, try <code>SetInfoLevel(InfoACE, 2);</code> before calling <code>ACEExample</code>,
with an example.

If you unexpectedly observe <code>aceexampleoptions</code> in your output, then
most probably you have unintentionally passed options by the global
method, by having a non-empty <code>OptionsStack</code>. One possible remedy is
to use <code>FlushOptionsStack();</code> (see <a href="CHAP004.htm#SSEC002.1">FlushOptionsStack</a>), before trying
your <code>ACEExample</code> call again.

As discussed in Section <a href="CHAP004.htm#SECT006">Interpretation of ACE Options</a>, there is
generally no sensible meaning that can be attributed to setting a
strategy option (see Chapter <a href="CHAP005.htm">Strategy Options for ACE</a>) to <code>false</code>;
if you wish to nullify the effect of a strategy option, pass another
strategy option, e.g. pass the <code>default</code> (see <a href="CHAP005.htm#SSEC001.1">option default</a>)
strategy option.

Also provided are:

<a name = "SSEC006.2"></a>
<li><code>ACEReadResearchExample( </code><var>filename</var><code> ) F</code>
<li><code>ACEReadResearchExample() F</code>

which perform <code>Read</code> (see Section <a href="../../../doc/ref/chap9.html#X8373AC6B7D5F9167">Read</a> in the GAP Reference
Manual) on <var>filename</var> or, with no argument, the file with filename
<code>"pgrelfind.g"</code> in the <code>res-examples</code> directory; e.g. the effect of
running

<pre>
gap> ACEReadResearchExample("pgrelfind.g");

</pre>

is equivalent to executing:

<pre>
gap> Read( Filename(DirectoriesPackageLibrary("ace", "res-examples"),
> "pgrelfind.g") );

</pre>

The examples provided in the <code>res-examples</code> directory were used to
solve a genuine research problem, the results of which are reported in
<a href="biblio.htm#CHHR01"><cite>CHHR01</cite></a>. Please see Section <a href="CHAP00B.htm#SECT005">Using ACEReadResearchExample</a> for
a detailed description and examples of its use.

<a name = "SSEC006.3"></a>
<li><code>ACEPrintResearchExample( </code><var>example-filename</var><code> ) F</code>
<li><code>ACEPrintResearchExample( </code><var>example-filename</var><code>, </code><var>output-filename</var><code>) F</code>

print the ``essential'' contents of the file <var>example-filename</var> in the
<code>res-examples</code> directory to the terminal, or with two arguments to the
file <var>output-filename</var>; <var>example-filename</var> and <var>output-filename</var>
should be strings. <code>ACEPrintResearchExample</code> is provided to make it
easy for users to copy and edit the examples for their own purposes.


<h2><a name="SECT007">1.7 General Warnings regarding the Use of Options</a></h2>

Firstly, let us mention (and we will remind you later) that an ACE
strategy is merely a special option of ACE that sets a number of
the options described in Chapter <a href="CHAP004.htm">Options for ACE</a> all at once. The
strategy options are discussed in their own chapter (Chapter <a href="CHAP005.htm">Strategy Options for ACE</a>).

In Section <a href="CHAP004.htm#SECT001">Passing ACE Options</a>, we describe the two means provided
by GAP by which ACE options may be passed. In Section <a href="CHAP004.htm#SECT002">Warnings regarding Options</a>, we discuss how options ``left over'' from previous
calculations can upset subsequent calculations; and hence, to ``clear
the decks'' in such circumstances, why we have provided
<code>FlushOptionsStack</code> (see <a href="CHAP004.htm#SSEC002.1">FlushOptionsStack</a>). However, removing
<code>OptionsStack</code> options does not remove the options previously passed
to an interactive ACE process; Section <a href="CHAP004.htm#SECT002">Warnings regarding Options</a> discusses that too.

Note, that the ACE package treatment of options is an
``enhancement'' over the general way GAP treats options. Firstly,
the ACE binary allows abbreviations and mixed case of options and
so the ACE package does also, as much as is possible
(see <a href="CHAP004.htm#SECT003">Abbreviations and mixed case for ACE Options</a>). Secondly, since
ACE's options are in general not orthogonal, the order in which
they are put to ACE is, in general, honoured (see <a href="CHAP004.htm#SECT004">Honouring of the order in which ACE Options are passed</a>). Thirdly, the ACE binary's
concept of a boolean option is slightly different to that of GAP's;
Section <a href="CHAP004.htm#SECT006">Interpretation of ACE Options</a> discusses, in particular, how
an option detected by GAP as <code>true</code> is passed to the ACE binary.

Finally, Section <a href="CHAP004.htm#SECT005">What happens if no ACE Strategy Option or if no ACE Option is passed</a> discusses what happens if no option is selected.


<h2><a name="SECT008">1.8 The ACEData Record</a></h2>

<a name = "SSEC008.1"></a>
<li><code>ACEData V</code>

is a GAP record in which the essential data for an ACE session
within GAP is stored; its fields are:


<dl compact>

<dt> <code>binary</code> <dd> the path of the ACE binary;

<dt> <code>tmpdir</code> <dd> the path of the temporary directory containing the
non-interactive ACE input and output files (also see
<a href="CHAP001.htm#SSEC008.2">ACEDirectoryTemporary</a> below);

<dt> <code>ni</code> <dd> the data record for a non-interactive ACE process;

<dt> <code>io</code> <dd> list of data records for <code>ACEStart</code> (see below
and <a href="CHAP006.htm#SSEC001.1">ACEStart</a>) processes;

<dt> <code>infile</code> <dd> the full path of the ACE input file;

<dt> <code>outfile</code><dd> the full path of the ACE output file; and

<dt> <code>version</code><dd> the version of the current ACE binary. More
detailed information regarding the compilation of the binary is given
by <code>ACEBinaryVersion</code> (see <a href="CHAP006.htm#SSEC005.25">ACEBinaryVersion</a>).

</dl>

Non-interactive processes used to use files rather than streams (hence
the fields <code>infile</code> and <code>outfile</code> above; these may disappear in a
later version of the ACE package).

Each time an interactive ACE process is initiated via <code>ACEStart</code>
(see <a href="CHAP006.htm#SSEC001.1">ACEStart</a>), an identifying number <var>ioIndex</var> is generated for the
interactive process and a record <code>ACEData.io[</code><var>ioIndex</var><code>]</code> with the
following fields is created. A non-interactive process has similar
fields but is stored in the record <code>ACEData.ni</code>.


<dl compact>

<dt> <code>procId</code> <dd> the identifying number of the process (<var>ioIndex</var> for
interactive processes, and 0 for a non-interactive process);

<dt> <code>args</code> <dd> a record with fields: <code>fgens</code>, <code>rels</code>, <code>sgens</code> whose
values are the corresponding arguments passed originally to
<code>ACEStart</code>;

<dt> <code>options</code><dd> the current options record of the interactive process;

<dt> <code>acegens</code><dd> a list of strings representing the generators used by
ACE (if the names of the generators passed via the first argument
<var>fgens</var> of <code>ACEStart</code> were all lowercase alphabetic characters, then
<code>acegens</code> is the <code>String</code> equivalent of <var>fgens</var>, i.e. <code>acegens[1] =
String(</code><var>fgens</var><code>[1])</code> etc.);

<dt> <code>stream</code> <dd> the IOStream opened for an interactive ACE process
initiated via <code>ACEStart</code>; and

<dt> <code>enumResult</code> <dd>
the enumeration result (string) without the trailing newline, output
from ACE;

<dt> <code>stats</code> <dd> a record as output by the function <code>ACEStats</code>.

<dt> <code>enforceAsis</code> <dd>
a boolean that is set to <code>true</code> whenever the <code>asis</code> option
(see <a href="CHAP004.htm#SSEC013.1">option asis</a>) must be set to <code>1</code>. It is usually <code>false</code>.
See <a href="CHAP001.htm#SSEC002.3">IsACEGeneratorsInPreferredOrder</a> Guru Notes for the details.

</dl>

<a name = "SSEC008.2"></a>
<li><code>ACEDirectoryTemporary( </code><var>dir</var><code> ) F</code>

calls the UNIX command <code>mkdir</code> to create <var>dir</var>, which must be a
string, and if successful a directory object for <var>dir</var> is both
assigned to <code>ACEData.tmpdir</code> and returned. The fields <code>ACEData.infile</code>
and <code>ACEData.outfile</code> are also set to be files in <code>ACEData.tmpdir</code>,
and on exit from GAP <var>dir</var> is removed. Most users will never need
this command; by default, GAP typically chooses a ``random''
subdirectory of <code>/tmp</code> for <code>ACEData.tmpdir</code> which may occasionally
have limits on what may be written there. <code>ACEDirectoryTemporary</code>
permits the user to choose a directory (object) where one is not so
limited.


<h2><a name="SECT009">1.9 Setting the Verbosity of ACE via Info and InfoACE</a></h2>

<a name = "SSEC009.1"></a>
<li><code>InfoACE V</code>

The output of the ACE binary is, by default, not displayed. However
the user may choose to see some, or all, of this output. This is done
via the <code>Info</code> mechanism (see Chapter <a href="../../../doc/ref/chap7.html#X7A9C902479CB6F7C">Info Functions</a> in the
GAP Reference Manual). For this purpose, there is the <var>InfoClass</var>
<code>InfoACE</code>. Each line of output from ACE is directed to a call to
<code>Info</code> and will be displayed for the user to see if the <code>InfoLevel</code> of
<code>InfoACE</code> is high enough. By default, the <code>InfoLevel</code> of <code>InfoACE</code> is
1, and it is recommended that you leave it at this level, or higher.
Only messages which we think that the user will really want to see are
directed to <code>Info</code> at <code>InfoACE</code> level 1. To turn off all <code>InfoACE</code>
messaging, set the <code>InfoACE</code> level to 0 (see <a href="CHAP001.htm#SSEC009.1">InfoACE</a>).

Currently, information from
ACE is directed to <code>Info</code> at four <code>InfoACE</code> levels: 1, 2, 3 and 4.
The command

<pre>
gap> SetInfoLevel(InfoACE, 2);

</pre>

enables the display of the results line of an enumeration from ACE,
whereas

<pre>
gap> SetInfoLevel(InfoACE, 3);

</pre>

enables the display of all of the output from ACE (including
ACE's banner, containing the host machine information); in
particular, the progress messages, emitted by ACE when the
<code>messages</code> option (see <a href="CHAP004.htm#SSEC018.1">option messages</a>) is set to a non-zero value,
will be displayed via <code>Info</code>. Finally,

<pre>
gap> SetInfoLevel(InfoACE, 4);

</pre>

enables the display of all the input directed to ACE (behind a
``<code>ToACE> </code>'' prompt, so you can distinguish it from other output).
The <code>InfoACE</code> level of 4 is really for gurus who are familiar with the
ACE standalone.


<h2><a name="SECT010">1.10 Acknowledgements</a></h2>

Large parts of this manual, in particular the description of the
options for running ACE, are directly copied from the respective
descriptions in the manual <a href="biblio.htm#Ram99ace"><cite>Ram99ace</cite></a> for the standalone version of
ACE by Colin Ramsay. Most of the examples, in the <code>examples</code>
directory and accessed via the <code>ACEExample</code> function, are direct
translations of Colin Ramsay's test###.in files in the src
directory.

Many thanks to Joachim Neubüser who not only provided one
of the early manual drafts and hence a template for the style of the
manual and conceptual hooks for the design of the Package code, but
also meticulously proof-read all drafts and made many insightful
comments.

Many thanks also to Volkmar Felsch who, in testing the ACE Package,
discovered a number of bugs, made a number of important suggestions on
code improvement, thoroughly checked all the examples, and provided
the example found at the end of Section <a href="CHAP006.htm#SECT007">Steering ACE Interactively</a>
which demonstrates rather nicely how one can use the function
<code>ACEConjugatesForSubgroupNormalClosure</code>.

We also wish to acknowledge the contribution of Charles Sims. The
inclusion of the <code>incomplete</code> (see <a href="CHAP004.htm#SSEC011.6">option incomplete</a>) and <code>lenlex</code>
(see <a href="CHAP004.htm#SSEC011.4">option lenlex</a>) options, were made in response to requests to
the GAP developers to include such options for coset table
functions. Also, the definition of <code>lenlex</code> standardisation of coset
tables (see Section <a href="CHAP003.htm#SECT004">Coset Table Standardisation Schemes</a>), is due to
him.

Finally, much of the work since 2005 in modifying the ACE package
particularly for new versions of GAP and in getting ACE to its
new home on <code>GitHub</code> has been due to Max Horn.


<h2><a name="SECT011">1.11 Changes from earlier versions</a></h2>

A reasonably comprehensive history of the evolution of pre-release
versions of the ACE Package, is contained in the file <code>CHANGES</code> in
the <code>gap</code> directory.

The <code>3.xxx</code> versions of the ACE Package were compatible with GAP
4.2, but were built for use with GAP 4.3. However, the current
version of the ACE Package requires at least GAP 4.4. Users who
still have GAP 4.3 will need to use ACE 4.1. One important
change in GAP from GAP 4.2 to GAP 4.3 that has relevance for
ACE Package users is the change of the default standard for the
numbering of cosets in a coset table (see Section <a href="CHAP003.htm#SECT004">Coset Table Standardisation Schemes</a>).

<a name = "SSEC011.1"></a>
<li><code>ACEPackageVersion() F</code>

gives the current version of the ACE Package (i.e. the GAP code
component; the function <code>ACEBinaryVersion</code> (see <a href="CHAP006.htm#SSEC005.25">ACEBinaryVersion</a>)
gives details of the C code compilation).


[<a href = "chapters.htm">Up</a>] [<a href ="CHAP002.htm">Next</a>] [<a href = "theindex.htm">Index</a>]

<address>ACE manual April 2025
</address></body></html>

quality99%

¤ Dauer der Verarbeitung: 0.21 Sekunden (vorverarbeitet) ¤

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.