6 Functions for Using ACE Interactively

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

All forms of ACEStart accept options described in Chapters Options for ACE and Strategy Options for ACE, and Appendix Other ACE Options, which are listed behind a colon in the usual way (see Function Calls in the GAP Reference Manual). The reader is strongly encouraged to read the introductory sections of Chapter Options for ACE, with regard to options. The global mechanism (via PushOptions) of passing options is not recommended for use with the interactive ACE interface functions; please ensure the OptionsStack is empty before calling an interactive ACE interface function.

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

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

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

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

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

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

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

The sixth form of ACEStart (on four arguments), is like the first form of ACEStart (on three arguments), except that it does not insert a start (see option start) directive. It initiates an interactive ACE process, with a presentation defined by its last 3 arguments.

The seventh form of ACEStart (on two arguments), is like the second form of ACEStart (on one argument), except that it does not insert a start (see option start) directive. It processes any new options for the ith interactive ACE process. ACEStart(0, i [: options ] ), is similar to SetACEOptions(i [: options ] ) (see SetACEOptions), but unlike the latter does not invoke a general mode (see Section General ACE Modes).

The last form of ACEStart (on five arguments), is like the fourth form of ACEStart (on four arguments), except that it does not insert a start (see option start) directive. It re-uses an existing interactive ACE process, with a new presentation. There is no form of ACEStart with the same functionality as this form, where the i argument is omitted.

Note: When an interactive ACE process is initiated by ACEStart a process number i is assigned to it (the integer i returned by the ACEStart command), an ACE (binary) process (in the UNIX sense) is started up, a GAP iostream is assigned to communicate with the ACE (binary) process, and the essential ``defining'' data associated with the interactive ACE process is saved in ACEData.io[i] (see ACEData for precisely what is saved).

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

Note: ACEQuit(i) terminates the ACE (binary) process of interactive ACE process i, and closes its GAP iostream, and unbinds the record ACEData.io[i] (see ACEStart note).

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

is provided as a convenience, to terminate all active interactive ACE processes with a single command. It is equivalent to executing ACEQuit(i) for all active interactive ACE processes i (see ACEQuit).

6.2 General ACE Modes

For our purposes, we define an interactive ACE interface command to be an ACE mode, if it delivers an enumeration result (see Section Results messages). Thus, ACEStart (see ACEStart), except when called with the argument 0, and the commands ACERedo and ACEContinue which we describe below are ACE modes; we call these general ACE modes. Additionally, there are two other commands which deliver enumeration results: ACEAllEquivPresentations (see ACEAllEquivPresentations) and ACERandomEquivPresentations (see ACERandomEquivPresentations); we call these ``experimentation'' ACE modes and describe them in Section Experimentation ACE Modes.

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

After changing any of ACE's parameters, one of three general modes is possible: one may be able to ``continue'' via ACEContinue (see ACEContinue), or ``redo'' via ACERedo (see ACERedo), or if neither of these is possible one may have to re-``start'' the enumeration via ACEStart (see ACEStart). Generally, the appropriate mode is invoked automatically when options are changed; so most users should be able to ignore the following three functions.

for the ith (or default) interactive ACE process, return a record whose fields are the modes ACEStart, ACEContinue and ACERedo, and whose values are true if the mode is possible for the process and false otherwise.

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

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

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

6.3 Interactive ACE Process Utility Functions and Interruption of an Interactive ACE Process

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

Note: Essentially, an interactive ACE process i is ``active'' if ACEData.io[i] is bound (i.e. we still have some data telling us about it). Also see ACEStart note.

returns the list of integer indices of all active interactive ACE processes (see ACEProcessIndex for the meaning of ``active'').

return true if the GAP iostream of the ith (or default) interactive ACE process started by ACEStart is alive (i.e. can still be written to), or false, otherwise. (See the notes for ACEStart and ACEQuit.)

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

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

re-generate the GAP iostream of the ith (or default) interactive ACE process started by ACEStart (see ACEStart, the final note, in particular), and try to recover as much as possible of the previous state from saved values of the process's arguments and parameter options. The possible options here are use and useboth which are described in detail below.

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

By default, ACEResurrectProcess recovers parameter option information from ACEData.io[i].options if it is bound, or from ACEData.io[i].parameters if it is bound, otherwise. The ACEData.io[i].options record, however, is first filtered for parameter and strategy options (see Sections ACEParameterOptions and The ACEStrategyOptions list) and the echo option (see option echo). To alter this behaviour, the user is provided two options:

 use := useList

useList may contain one or both of "options" and "parameters". By default, use = ["options", "parameters"].

 useboth

(A boolean option). By default, useboth = false.

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

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

ACEResurrectProcess does not invoke an ACE mode (see Section General ACE Modes). This leaves the user free to use SetACEOptions (which does invoke an ACE mode) to further modify options afterwards.

This function produces, from a GAP list fgens of free group generators, the ACE directive string required by the group (see option group) option. (The group option may be used to define the equivalent of fgens in an ACE process.)

This function produces, from a GAP list words in free group generators fgens, a string that represents those words as an ACE list of words. ToACEWords may be used to provide suitable values for the options relators (see option relators), generators (see option generators), sg (see option sg), and rl (see option rl).

6.4 Experimentation ACE Modes

Now we describe the two experimentation modes. The term mode was defined in Section General ACE Modes.

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

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

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

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

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

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

As discussed by Cannon, Dimino, Havas and Watson CDHW73 and Havas and Ramsay HR01 such equivalent presentations can yield large variations in the number of coset numbers required in an enumeration. For this command, we are interested in this variation.

After the final presentation is run, some additional status information messages are printed to the ACE output:

• the number of runs which yielded a finite index;

• the total number of runs (excluding the priming run); and

• the range of values observed for m and t.

As an example (drawn from the discussion in HR99ace) consider the enumeration of the 448 coset numbers of the subgroup �a²,a^-1b � of the group

(8,7 | 2,3) = �a,b | a8 = b7 = (ab)2 = (a-1b)3 = 1 �·

There are 4!=24 relator orderings and 2⁴=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 val = 7 (resp. 3), 24·16·4=1536 (resp. 16·4=64) equivalent presentations are tested.

Now we describe the output of ACEAllEquivPresentations; it is a record with fields:

 primingResult

the ACE enumeration result message (see Section Results Messages) of the priming run;

 primingStats

the enumeration result of the priming run as a GAP record with fields index, cputime, cputimeUnits, activecosets, maxcosets and totcosets, exactly as for the record returned by ACEStats (see ACEStats);

 equivRuns

a list of data records, one for each progressively ``best'' run, where each record has fields:

  rels

the relators in the order used for the run,

  enumResult

the ACE enumeration result message (see Section Results Messages) of the run, and

  stats

the enumeration result as a GAP record exactly like the record returned by ACEStats (see ACEStats);

 summary

a record with fields:

  successes

the total number of successful (i.e. having finite enumeration index) runs,

  runs

the total number of equivalent presentation runs executed,

  maxcosetsRange

the range of values as a GAP list inside which each equivRuns[i].maxcosets lies, and

  totcosetsRange

the range of values as a GAP list inside which each equivRuns[i].totcosets lies.

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

There is no way to stop the ACEAllEquivPresentations command before it has completed, other than killing the task. So do a reality check beforehand on the size of the search space and the time for each enumeration. If you are interested in finding a ``good'' enumeration, it can be very helpful, in terms of running time, to put a tight limit on the number of coset numbers via the max option. You may also have to set compaction = 100 to prevent time-wasting attempts to recover space via compaction. This maximises throughput by causing the ``bad'' enumerations, which are in the majority, to overflow quickly and abort. If you wish to explore a very large search-space, consider firing up many copies of ACE, and starting each with a ``random'' equivalent presentation. Alternatively, you could use the ACERandomEquivPresentations command.

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

The routine first turns asis (see option asis) on and messages (see option messages) off (i.e. sets messages to 0), and then generates and tests the requested number of random equivalent presentations. For each presentation, the relators used and the summary result line are printed by ACE. To observe these messages set the InfoLevel of InfoACE to at least 3.

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

 rels

the relators in the order used for the run,

 enumResult

the ACE enumeration result message (see Section Results Messages) of the run, and

 stats

the enumeration result as a GAP record exactly like the record returned by ACEStats (see ACEStats).

Notes: The relator inversions and rotations are ``genuinely'' random. The relator permuting is a little bit of a kludge, with the ``quality'' of the permutations tending to improve with successive presentations. When the ACERandomEquivPresentations command completes, the presentation active is the last one generated.

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

6.5 Interactive Query Functions and an Option Setting Function

return the GAP group generators of the ith (or default) interactive ACE process. If no generators have been saved for the interactive ACE process, possibly because the process was started via ACEStart(0); (see ACEStart), the ACE process is interrogated, and the equivalent in GAP is saved and returned. Essentially, ACEGroupGenerators(i) interrogates ACE and establishes ACEData.io[i].args.fgens, if necessary, and returns ACEData.io[i].args.fgens. As a side-effect, if any of the remaining fields of ACEData.io[i].args or ACEData.io[i].acegens are unset, they are also set. Note that GAP provides GroupWithGenerators (see GroupWithGenerators in the GAP Reference Manual) to establish a free group on a given set of already-defined generators.

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

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

display the arguments (i.e. fgens, rels and sgens) of the ith (or default) process started by ACEStart. In fact, DisplayACEArgs(i) is just a pretty-printer of the ACEData.io[i].args record. Use GetACEArgs (see GetACEOptions) in assignments. Unlike ACEGroupGenerators (see ACEGroupGenerators), ACERelators (see ACERelators) and ACESubgroupGenerators (see ACESubgroupGenerators), DisplayACEArgs does not have the side-effect of setting any of the fields of ACEData.io[i].args if they are unset.

return a record of the current arguments (i.e. fgens, rels and sgens) of the ith (or default) process started by ACEStart. In fact, GetACEOptions(i) simply returns the ACEData.io[i].args record, or an empty record if that record is unbound. Unlike ACEGroupGenerators (see ACEGroupGenerators), ACERelators (see ACERelators) and ACESubgroupGenerators (see ACESubgroupGenerators), GetACEOptions does not have the side-effect of setting any of the fields of ACEData.io[i].args if they are unset.

display the options, explicitly set by the user, of the ith (or default) process started by ACEStart. In fact, DisplayACEOptions(i) is just a pretty-printer of the ACEData.io[i].options record. Use GetACEOptions (see GetACEOptions) in assignments. Please note that no-value ACE options will appear with the assigned value true (see Section Interpretation of ACE Options for how the ACE interface functions interpret such options).

Notes: Any options set via ACEWrite (see ACEWrite) will not be displayed. Also, recall that if ACE is not given any options it uses the default strategy (see Section What happens if no ACE Strategy Option or if no ACE Option is passed). To discover the various settings of the ACE Parameter Options (see ACEParameterOptions) in vogue for the ACE process, use ACEParameters (see ACEParameters).

return a record of the current options (those that have been explicitly set by the user) of the ith (or default) process started by ACEStart. Please note that no-value ACE options will appear with the assigned value true (see Section Interpretation of ACE Options for how the ACE interface functions interpret such options). The notes applying to DisplayACEOptions (see DisplayACEOptions) also apply here.

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

After setting the options passed, the first mode of the following: ACEContinue (see ACEContinue), ACERedo (see ACERedo) or ACEStart (see ACEStart), that may be applied, is automatically invoked.

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

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

gap> ACEExample("A5", ACEStart);

then the following demonstrates both usages of SetACEOptions:

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

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

Notes:

When ACECosetTableFromGensAndRels enters a break-loop (see ACECosetTable), local versions of the second form of each of DisplayACEOptions and SetACEOptions become available. (Even though the names are similar and their function is analogous they are in fact different functions.)

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

Notes: One use for this function might be to determine the options required to replicate a previous run, but be sure that, if this is your purpose, any recent change in the parameter option values has been followed by an invocation of one of ACEContinue (see ACEContinue), ACERedo (see ACERedo) or ACEStart (see ACEStart).

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

return, for the ith (or default) process started by ACEStart, true if ACE's current coset table is complete, or false otherwise.

Note: The completeness of the coset table of the ith interactive ACE process is determined by checking whether ACEData.io[i].stats.index is positive; a value of zero indicates the last enumeration failed to complete. The record ACEData.io[i].stats is what is returned by ACEStats(i) (see ACEStats).

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

Note: The coset table displayed will normally only be lenlex standardised if the call to ACEDisplayCosetTable is preceded by ACEStandardCosetNumbering (see ACEStandardCosetNumbering). The options lenlex (see option lenlex) and semilenlex (see option semilenlex) are only executed by ACECosetTable (see ACECosetTable). The ACE binary does not provide semilenlex standardisation, and hence ACEDisplayCosetTable will never display a semilenlex standard coset table.

return, for the ith (or default) process started by ACEStart, the coset representative of coset n of the current coset table held by ACE, where n must be a positive integer.

return, for the ith (or default) process started by ACEStart, the list of coset representatives of the current coset table held by ACE.

return, for the ith (or default) process started by ACEStart, the list of coset representatives of the current coset table held by ACE, if the current table is complete, and fail otherwise. Essentially, ACETransversal(i) = ACECosetRepresentatives(i) for a complete table.

return, for the ith (or default) process started by ACEStart, a list of permutations corresponding to the group generators, (i.e., the permutation representation), if the current coset table held by ACE is complete or fail, otherwise. In the event of failure a message is emitted to Info at InfoACE or InfoWarning level 1.

for the ith (or default) interactive ACE process started by ACEStart, trace word through ACE's coset table, starting at coset n, and return the final coset number if the trace completes, and fail otherwise. In Group Theory terms, if the cosets of a subgroup H in a group G are the subject of interactive ACE process i and the coset identified by that process by the integer n corresponds to some coset Hx, for some x in G, and word represents the element g of G, then, providing the current coset table is complete enough, ACETraceWord( i, n, word ) returns the integer identifying the coset Hxg.

Notes: You may wish to compact ACE's coset table first, either explicitly via ACERecover (see ACERecover), or, implicitly, via any function call that invokes ACE's compaction routine (see ACERecover note).

If you actually wanted ACE's coset representative, then, for a compact table, feed the output of ACETraceWord to ACECosetRepresentative (see ACECosetRepresentative).

for the ith (or default) interactive ACE process started by ACEStart, search for all coset numbers whose representatives' orders (modulo the subgroup) are either finite, or, if invoked with the suborder option, are multiples of suborder, where suborder should be a positive integer. ACEOrders returns a (possibly empty) list of records, each with fields coset, order and rep, which are respectively, the coset number, its order modulo the subgroup, and a representative for each coset number satisfying the criteria of the search.

Note: You may wish to compact ACE's coset table first, either explicitly via ACERecover (see ACERecover), or, implicitly, via any function call that invokes ACE's compaction routine (see ACERecover note).

for the ith (or default) interactive ACE process started by ACEStart, search for coset number(s) whose coset representatives have order modulo the subgroup a multiple of suborder. When suborder is a positive integer, ACEOrder returns just one record with fields coset, order and rep, which are respectively, the coset number, its order modulo the subgroup, and a representative for the first coset number satisfying the criteria of the search, or fail if there is no such coset number. The value of suborder may also be a negative integer, in which case, ACEOrder( i, suborder ) is equivalent to ACEOrders( i : suborder := |suborder|); or suborder may be zero, in which case, ACEOrder( i, 0 ) is equivalent to ACEOrders( i ).

Note: You may wish to compact ACE's coset table first, either explicitly via ACERecover (see ACERecover), or, implicitly, via any function call that invokes ACE's compaction routine (see ACERecover note).

for the ith (or default) interactive ACE process return the order (modulo the subgroup) of the coset with representative cosetrep, a word in the free group generators.

Note: ACECosetOrderFromRepresentative calls ACETraceWord to determine the coset (number) to which cosetrep belongs, and then scans the output of ACEOrders to determine the order of the coset (number).

for the ith (or default) interactive ACE process started by ACEStart, determine non-trivial (i.e. other than coset 1) coset numbers whose representatives normalise the subgroup.

• If n > 0, the list of the first n non-trivial coset numbers whose representatives normalise the subgroup is returned.

• If n < 0, a list of records with fields coset and rep which represent the coset number and a representative, respectively, of the first n non-trivial coset numbers whose representatives normalise the subgroup is returned.

• If n = 0, a list of records with fields coset and rep which represent the coset number and a representative, respectively, of all non-trivial coset numbers whose representatives normalise the subgroup is returned.

Note: You may wish to compact ACE's coset table first, either explicitly via ACERecover (see ACERecover), or, implicitly, via any function call that invokes ACE's compaction routine (see ACERecover note).

returns the current enumeration style as one of the strings: "C", "Cr", "CR", "R", "R*", "Rc", "R/C", or "R/C (defaulted)" (see Section Enumeration Style).

The next two functions of this section are really intended for ACE standalone gurus. To fully understand their output you will need to consult the standalone manual and the C source code.

dump the internal variables of ACE of the ith (or default) process started by ACEStart; level should be one of 0, 1, or 2, and detail should be 0 or 1.

The value of level determines which of the three levels of ACE to dump. (You will need to read the standalone manual to understand what Levels 0, 1 and 2 are all about.) The value of detail determines the amount of detail (detail = 0 means less detail). The first two forms of ACEDumpVariables (with no list argument) selects level = 0, detail = 0. The third and fourth forms (with a list argument containing the integer level) makes detail = 0. This command is intended for gurus; the source code should be consulted to see what the output means.

dump ACE's internal statistics accumulated during the most recent enumeration of the ith (or default) process started by ACEStart, provided the ACE binary was built with the statistics package (which it is by default). Use ACEBinaryVersion(); (see ACEBinaryVersion) to check for the inclusion of the statistics package. See the enum.c source file for the meaning of the variables.

for the ith (or default) process started by ACEStart, print, via Info (at InfoACE level 1), version details of the ACE binary you are currently running, including what compiler flags were set when the executable was built, and also returns the version number of the binary as a string. Essentially the information obtained is what is obtained via ACE's options option (see option options), and the returned value is what is stored in ACEData.version (see ACEData). A typical output, illustrating the default build, is:

gap> ACEBinaryVersion();
#I  No interactive ACE sessions are currently active
#I  ACE Binary Version: 3.001
#I  ACE 3.001        Sat Feb 27 11:27:15 2016
#I  =========================================
#I  Host information:
#I    name = banksia
#I  ACE 3.001 executable built:
#I    Wed Feb 24 15:25:26 AWST 2016
#I  Level 0 options:
#I    statistics package = on
#I    coinc processing messages = on
#I    dedn processing messages = on
#I  Level 1 options:
#I    workspace multipliers = decimal
#I  Level 2 options:
#I    host info = on
"3.001"

Notes: The ACE binary's banner may also appear in the output (if it has not already appeared). Unlike other ACE interface functions, the information obtained via ACEBinaryVersion(); is absolutely independent of any enumeration. For this reason, we make it permissible to run ACEBinaryVersion(); when there are no currently active interactive ACE processes; and, in such a case, ACEBinaryVersion(); emits a warning that there are no interactive ACE sessions currently active and initiates (and closes again) its own stream to obtain the information from the ACE binary. For the current version of the ACE package (the GAP code component) use ACEPackageVersion(); (see ACEPackageVersion).

6.6 Interactive Versions of Non-interactive ACE Functions

return a coset table as a GAP object, in standard form (for GAP). These functions perform the same function as ACECosetTableFromGensAndRels and ACECosetTable on three arguments (see ACECosetTable), albeit interactively, on the ith (or default) process started by ACEStart. If options are passed then an internal version of ACEModes is run to determine which of the general ACE modes (see Section General ACE Modes) ACEContinue, ACERedo or ACEStart is possible; and (an internal version of) the first mode of these that is allowed is executed, to ensure the resultant table is correct for the current options.

perform the same function as ACEStats on three arguments (see ACEStats --- non-interactive version), albeit interactively, on the ith (or default) process started by ACEStart. If options are passed then an internal version of ACEModes is run to determine which of the general ACE modes (see Section General ACE Modes) ACEContinue, ACERedo or ACEStart is possible; and (an internal version of) the first mode of these that is allowed is executed, to ensure the resultant statistics are correct for the current options.

See Section Example of Using ACE Interactively (Using ACEStart) for an example demonstrating both these functions within an interactive process.

for the ith (or default) interactive ACE process started by ACEStart, return true if the group generators of that process, are in an order that will not be changed by ACE, and false otherwise. This function has greatest relevance to users who call ACECosetTable (see ACECosetTable!interactive), with the lenlex option (see option lenlex). For more details, see the discussion for the non-interactive version of IsACEGeneratorsInPreferredOrder (IsACEGeneratorsInPreferredOrder), which is called with two arguments.

6.7 Steering ACE Interactively

invoke the compaction routine on the coset table of the ith (or default) interactive ACE process started by ACEStart, in order to recover the space used by the dead coset numbers. A CO message line is printed if any rows of the coset table were recovered, and a co line if none were. (See Appendix The Meanings of ACE's output messages for the meanings of these messages.)

Note: The compaction routine is called automatically when any of ACEDisplayCosetTable (see ACEDisplayCosetTable), ACECosetRepresentative (see ACECosetRepresentative), ACECosetRepresentatives (see ACECosetRepresentatives), ACETransversal (see ACETransversal), ACECycles (see ACECycles), ACEStandardCosetNumbering (see ACEStandardCosetNumbering), ACECosetTable (see ACECosetTable) or ACEConjugatesForSubgroupNormalClosure (see ACEConjugatesForSubgroupNormalClosure), is invoked.

compact and then do a lenlex standardisation (see Section Coset Table Standardisation Schemes) of the numbering of cosets in the coset table of the ith (or default) interactive ACE process started by ACEStart. That is, for a given ordering of the generators in the columns of the table, they produce a canonic table. A table that includes a column for each generator inverse immediately following the column for the corresponding generator, standardised according to the lenlex scheme, has the property that a row-major scan (i.e. a scan of the successive rows of the body of the table row by row, from left to right) encounters previously unseen cosets in numeric order. This function does not display the new table; use ACEDisplayCosetTable (see ACEDisplayCosetTable) for that.

Notes: In a lenlex canonic table, the coset representatives are ordered first according to length and then the lexicographic order defined by the order the generators and their inverses head the columns. Note that, unless special action is taken, ACE avoids having an involutory generator in the first column (by swapping the first two generators), except when there is only one generator, or when the second generator is also an involution; so the lexicographic order used by ACE need not necessarily correspond with the order in which the generators were first put to ACE. (We have used the term ``involution'' above; what we really mean is a generator x for which there is a relator x*x or x^2. Such a generator may, of course, turn out to actually be the identity.) The function IsACEGeneratorsInPreferredOrder (see IsACEGeneratorsInPreferredOrder) detects cases when ACE would swap the first two generators.

Standardising the coset numbering within ACE does not affect the GAP coset table obtained via ACECosetTable (see ACECosetTable). If ACECosetTable is called without the lenlex option GAP's default standardisation is applied after conversion of ACE's output, which undoes an ACE standardisation. On the other hand, if ACECosetTable is called with the lenlex option then after a check and special action, if required, the equivalent of a call to ACEStandardCosetNumbering is invoked, irrespective of whether it has been done by the user beforehand. The check that is done is a call to IsACEGeneratorsInPreferredOrder (see IsACEGeneratorsInPreferredOrder) to ensure that ACE has not swapped the first two generators. The special action taken when the call to IsACEGeneratorsInPreferredOrder returns false, is the setting of the asis option (see option asis) to 1 and the resubmission of the relators to ACE taking care not to submit the relator that determines the first generator as an involution as that generator squared (these two actions together avert ACE's swapping of the first two generators), followed by the re-starting of the enumeration.

Guru Notes: In five of the ten standard enumeration strategies of Sims Sim94 (i.e. the five Sims strategies not provided by ACE), the table is standardised repeatedly. This is expensive computationally, but can result in fewer cosets being necessary. The effect of doing this can be investigated in ACE by (repeatedly) halting the enumeration (via restrictive options), standardising the coset numbering, and continuing (see Section Emulating Sims for an example).

add, for the ith (or default) interactive ACE process started by ACEStart, the words in the list wordlist to any relators already present, and automatically invoke ACERedo, if it can be applied, or otherwise ACEStart. Note that ACE sorts the resultant relator list, unless the asis option (see option asis) has been set to 1; don't assume, unless asis = 1, that the new relators have been appended in user-provided order to the previously existing relator list. ACEAddRelators also returns the new relator list. Use ACERelators (see ACERelators) to determine the current relator list.

add, for the ith (or default) interactive ACE process started by ACEStart, the words in the list wordlist to any subgroup generators already present, and automatically invoke ACERedo, if it can be applied, or otherwise ACEStart. Note that ACE sorts the resultant subgroup generator list, unless the asis option (see option asis) has been set to 1; don't assume, unless asis = 1, that the new subgroup generators have been appended in user-provided order to the previously existing subgroup generator list. ACEAddSubgroupGenerators also returns the new subgroup generator list. Use ACESubgroupGenerators (see ACESubgroupGenerators) to determine the current subgroup generator list.

for the ith (or default) interactive ACE process started by ACEStart, delete list from the current relators, if list is a list of words in the group generators, or those current relators indexed by the integers in list, if list is a list of positive integers, and automatically invoke ACEStart. ACEDeleteRelators also returns the new relator list. Use ACERelators (see ACERelators) to determine the current relator list.

for the ith (or default) interactive ACE process started by ACEStart, delete list from the current subgroup generators, if list is a list of words in the group generators, or those current subgroup generators indexed by the integers in list, if list is a list of positive integers, and automatically invoke ACEStart. ACEDeleteSubgroupGenerators also returns the new subgroup generator list. Use ACESubgroupGenerators (see ACESubgroupGenerators) to determine the current subgroup generator list.

for the ith (or default) interactive ACE process started by ACEStart, return the representative of coset n, where n must be a positive integer, and add it to the subgroup generators; i.e., equates this coset with coset 1, the subgroup. ACERedo is automatically invoked.

for the ith (or default) interactive ACE process started by ACEStart, attempt up to attempts (or, in the first four forms, 8) times to find nontrivial subgroups with index a multiple of subindex by repeatedly making random coset numbers coincident with coset 1 and seeing what happens. The starting coset table must be non-empty, but must not be complete (use ACERandomlyApplyCosetCoincidence (see ACERandomlyApplyCosetCoincidence) if your table is already complete). For each attempt, by applying ACE's rc option (see option rc) random coset representatives are repeatedly added to the subgroup and the enumeration redone. If the table becomes too small, the attempt is aborted, the original subgroup generators restored, and another attempt made. If an attempt succeeds, then the new set of subgroup generators is retained. ACERandomCoincidences returns the list of new subgroup generators added. Use ACESubgroupGenerators (see ACESubgroupGenerators) to determine the current subgroup generator list.

Notes: ACERandomCoincidences may add subgroup generators even if it failed to determine a nontrivial subgroup with index a multiple of subindex; in such a case, the original status may be restored by applying ACEDeleteSubgroupGenerators (see ACEDeleteSubgroupGenerators) with the list returned by ACERandomCoincidences.

ACERandomCoincidences applies the rc option (see option rc) of ACE which takes the line that if an enumeration has already obtained a finite index then either, subindex is already a divisor of that finite index, or the request is impossible. Thus an invocation of ACERandomCoincidences, in the case where the coset table is already complete, is an error.

Guru Notes: A coset can have many different representatives. Consider running ACEStandardCosetNumbering (see ACEStandardCosetNumbering) before ACERandomCoincidences, to canonicise the table and the representatives.

for the ith (or default) interactive ACE process started by ACEStart, try to find a larger proper subgroup (i.e. a subgroup of smaller but nontrivial index), by repeatedly applying ACECosetCoincidence (see ACECosetCoincidence) and seeing what happens; ACERandomlyApplyCosetCoincidence returns the (possibly empty) list of new subgroup generators added. The starting coset table must already be complete (use ACERandomCoincidences (see ACERandomCoincidences) if your table is not already complete). ACERandomlyApplyCosetCoincidence provides the following four options (controlOptions).

 subindex := subindex

Sets the restriction that the final index should be a multiple of subindex; subindex must be a positive integer divisor of the initial subgroup index.

 hibound := hibound

Sets the restriction that the final index should be (strictly) less than hibound; hibound must be an integer that is greater than 1 and at most the initial subgroup index.

 lobound := lobound

Sets the restriction that the final index should be (strictly) greater than lobound; lobound must be an integer that is at least 1 and (strictly) less than the initial subgroup index.

 attempts := attempts

Sets the restriction that the number of applications of ACECosetCoincidence should be at most attempts; attempts must be a positive integer.

By default, subindex = 1, hibound is the existing subgroup index, lobound = 1 and attempts = 8. If after an attempt the new index is a multiple of subindex, less than hibound and greater than lobound then the process terminates (and the list of new subgroup generators is returned). Otherwise, if an attempt reaches a stage where the criteria cannot be satisfied, the attempt is aborted, the original subgroup generators restored, and another attempt made. If no attempt is successful an empty list is returned. Use ACESubgroupGenerators (see ACESubgroupGenerators) to determine the current subgroup generator list.

for the ith (or default) interactive ACE process started by ACEStart, test each conjugate of a subgroup generator by a group generator for membership in the subgroup, and return the (possibly empty) list of conjugates that were determined to not belong to the subgroup (coset 1); and, if called with the add option, these conjugates are also added to the existing list of subgroup generators.

Notes: A conjugate of a subgroup generator is tested for membership of the subgroup, by checking whether it can be traced from coset 1 to coset 1 (see ACETraceWord: ACETraceWord). For an incomplete coset table, such a trace may not complete, in which case ACEConjugatesForSubgroupNormalClosure may return an empty list even though the subgroup is not normally closed within the group.

The add option does not guarantee that the resultant subgroup is normally closed. It is still possible that some conjugates of the newly added subgroup generators will not be elements of the subgroup.

Example: To demonstrate the usage and features of ACEConjugatesForSubgroupNormalClosure, let us consider an example where we know pretty well what to expect.

Let G be the group, isomorphic to the symmetric group S₆, with the presentation

{ a, b | a2, b6, (ab-1ab)3, (ab-1ab2)4, (ab)5, (ab-2ab2)2 }

(from CM72), and let H be the subgroup �ab³ �. There is an isomorphism f from G to S₆ mapping a onto (1,2) and ab³ onto (1,2,3,4,5,6). It follows that f maps ab³ into A₆. So we know that the normal closure of H has index 2 in G. Let us observe this via ACE.

First we start an enumeration with max set to 80.

gap> F := FreeGroup( "a", "b" );;
gap> a := F.1;; b := F.2;;
gap> fgens := GeneratorsOfGroup( F );;
gap> rels := [ a^2, b^6, (a*b^-1*a*b)^3, (a*b^-1*a*b^2)^4, (a*b)^5,
>              (a*b^-2*a*b^2)^2 ];;
gap> sgens := [ a*b^3 ];;
gap> i := ACEStart( fgens, rels, sgens : max := 80 );;
gap> IsCompleteACECosetTable( i );
false
gap> ACEConjugatesForSubgroupNormalClosure( i : add );
#I  ACEConjugatesForSubgroupNormalClosure: All (traceable) conjugates in subgp
[  ]

Though we know that H is not equal to its normal closure, we did not get any new elements (we had warned above of such a possibility). Apparently our incomplete table is too small. So let us increase max to 100 and continue.

gap> ACEContinue( i : max := 100 );;
gap> IsCompleteACECosetTable( i );
false
gap> ACEConjugatesForSubgroupNormalClosure( i : add );
[ b^-1*a*b^4 ]
gap> IsCompleteACECosetTable( i );
true
gap> ACEStats( i ).index;
20

This time we got a new element, and after adding it to the subgroup generators we obtained a complete table. However the resulting subgroup need not yet be the normal closure of H (and in fact we know that it is not). So we continue with another call to the function ACEConjugatesForSubgroupNormalClosure.

gap> ACEConjugatesForSubgroupNormalClosure( i : add );
[ b^-2*a*b^5, b*a*b^2 ]
gap> ACEStats( i ).index;
2

Now we have the index that we expected. Another call to the function ACEConjugatesForSubgroupNormalClosure should not yield any more conjugates. We ensure that this is indeed the case and then display the resulting list of subgroup generators.

gap> ACEConjugatesForSubgroupNormalClosure( i : add );
#I  ACEConjugatesForSubgroupNormalClosure: All (traceable) conjugates in subgp
[  ]
gap> ACESubgroupGenerators( i );
[ a*b^3, b*a*b^2, b^-1*a*b^4, b^-2*a*b^5 ]

6.8 Primitive ACE Read/Write Functions

For those familiar with the workings of the ACE standalone we provide primitive read/write tools to communicate directly with an interactive ACE process, started via ACEStart (possibly with argument 0, but this is not essential). For the most part, it is up to the user to translate the output strings from ACE into a form useful in GAP. However, after the group generators, relators, and subgroup generators have been set in the ACE process, via ACEWrite, invocations of any of ACEGroupGenerators (see ACEGroupGenerators), ACERelators (see ACERelators), ACESubgroupGenerators (see ACESubgroupGenerators), or ACEParameters (see ACEParameters) will establish the corresponding GAP values. Be warned though, that unless one of the modes ACEStart (without a zero argument; see ACEStart), ACERedo (see ACERedo) or ACEContinue (see ACEContinue), or their equivalent for the standalone ACE (start;, redo;, or continue;), has been invoked since the last change of any parameter options (see ACEParameterOptions), some of the values reported by ACEParameters may well be incorrect.

write string to the ith or default interactive ACE process; string must be in exactly the form the ACE standalone expects. The command is echoed via Info at InfoACE level 4 (with a ``ToACE> '' prompt); i.e. SetInfoACELevel(4); will allow you to see what is transmitted to the ACE binary. ACEWrite returns true if successful in writing to the stream of the interactive ACE process, and fail otherwise.

Note: If ACEWrite returns fail (which means that the ACE process has died), you may like to try resurrecting the interactive ACE process via ACEResurrectProcess (see ACEResurrectProcess).

read a complete line of ACE output, from the ith or default interactive ACE process, if there is output to be read and returns fail otherwise. When successful, the line is returned as a string complete with trailing newline character. Please note that it is possible to be ``too quick'' (i.e. the return can be fail purely because the output from ACE is not there yet), but if ACERead finds any output at all, it waits for a complete line.

read and return as many complete lines of ACE output, from the ith or default interactive ACE process, as there are to be read, at the time of the call, as a list of strings with the trailing newlines removed and returns the empty list otherwise. ACEReadAll also writes each line read via Info at InfoACE level 3. Whenever ACEReadAll finds only a partial line, it waits for the complete line, thus increasing the probability that it has captured all the output to be had from ACE.

read complete lines of ACE output, from the ith or default interactive ACE process, ``chomps'' them (i.e. removes any trailing newline character), emits them to Info at InfoACE level 3, and applies the function Modify (where Modify is just the identity map/function for the first two forms) until a ``chomped'' line line for which IsMyLine( Modify(line) ) is true. ACEReadUntil returns the list of Modify-ed ``chomped'' lines read.

Notes: When provided by the user, Modify should be a function that accepts a single string argument.

IsMyLine should be a function that is able to accept the output of Modify (or take a single string argument when Modify is not provided) and should return a boolean.

If IsMyLine( Modify(line) ) is never true, ACEReadUntil will wait indefinitely.

[Up] [Previous] [Next] [Index]