[Up] [Previous] [Index]

D Other ACE Options

Sections

  1. Experimentation Options
  2. Options that Modify a Presentation
  3. Mode Options
  4. Options that Interact with the Operating System
  5. Query Options
  6. Options that Modify the Coset Table
  7. Options for Comments

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

D.1 Experimentation Options

  • aep:=val
    Runs the enumeration for all equivalent presentations; val is in the integer range 1 to 7.

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

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

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

    It then turns asis on and messages off (i.e. sets messages to 0), and generates and tests the requested equivalent presentations. The maximum and minimum values attained by m (the maximum number of coset numbers defined at any stage) and t (the total number of coset numbers defined) are tracked, and each time a new ``record'' is found, the relators used and the summary result line is printed. See Appendix The Meanings of ACE's output messages for a discussion of the statistics m and t. To observe these messages either set the InfoLevel of InfoACE to 3 or non-interactively you can peruse the ACE output file (see option aceoutfile).

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

    The order in which the equivalent presentations are generated and tested has no particular significance, but note that the presentation as given after the initial priming run) is the last presentation to be generated and tested, so that the group's relators are left unchanged by running the aep option, (not that a non-interactive user cares).

    As discussed by Cannon, Dimino, Havas and Watson 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 file:

    • 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 〈a2,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 24=16 combinations of relator or inverted relator. Exponents are taken into account when rotating relators, so the relators given give rise to 1, 1, 2 and 2 rotations respectively, for a total of 1·1·2·2=4 combinations. So, for aep = 7 (resp. 3), 24·16·4=1536 (resp. 16·4=64) equivalent presentations are tested.

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

    INTERACTIVELY, use ACEAllEquivPresentations (see ACEAllEquivPresentations).

  • rep:=val
  • rep:= [val, Npresentations]
    Run the enumeration for random equivalent presentations; val is in the integer range 1 to 7; Npresentations must be a positive integer.

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

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

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

    Notes: The relator inversions and rotations are ``genuinely'' random. The relator permuting is a little bit of a kludge, with the ``quality'' of the permutations tending to improve with successive presentations. When the rep command completes, the presentation active is the last one generated, (not that the non-interactive user cares).

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

    INTERACTIVELY, use ACERandomEquivPresentations (see ACERandomEquivPresentations).

  • D.2 Options that Modify a Presentation

  • group:=grpgens
    Defines the group generators; grpgens should be an integer (that is the number of generators) or a string that is the concatenation of, or a list of, single-lowercase-letter group generator names, i.e. it should be in a form suitable for the ACE binary to interpret. (Shortest abbreviation: gr.)

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

    To convert a GAP list fgens of free group generators into a form suitable for the group option, use the construction: ToACEGroupGenerators(fgens) (see ToACEGroupGenerators). It is strongly recommended that users of the group option use this construction.

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

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

  • relators:=relators
    Defines the group relators; relators must be a string or list of strings that the ACE binary can interpret as words in the group generators. (Shortest abbreviation: rel.)

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

    To convert a GAP list rels of relators in the free group generators fgens into a form suitable for the relators option, use the construction: ToACEWords(fgens, rels) (see ToACEWords).

  • generators:=subgens
    Defines the subgroup generators; subgens must be a string or list of strings that the ACE binary can interpret as words in the group generators. (Shortest abbreviation: gen.)

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

    To convert a GAP list sgens of subgroup generators in the free group generators fgens into a form suitable for the generators option, use the construction: ToACEWords(fgens, sgens) (see ToACEWords).

  • sg:=subgens
    Adds the words in subgens to any subgroup generators already present; subgens must be a string or list of strings that the ACE binary can interpret as words in the group generators.

    The enumeration must be (re)started or redone, it cannot be continued.

    To convert a GAP list sgens of subgroup generators in the free group generators fgens into a form suitable for the generators option, use the construction: ToACEWords(fgens, sgens) (see ToACEWords).

    INTERACTIVELY, use ACEAddSubgroupGenerators (see ACEAddSubgroupGenerators).

  • rl:=relators
    Appends the relator list relators to the existing list of relators present; relators must be a string or list of strings that the ACE binary can interpret as words in the group generators.

    The enumeration must be (re)started or redone, it cannot be continued.

    To convert a GAP list rels of relators in the free group generators fgens into a form suitable for the rl option, use the construction: ToACEWords(fgens, rels) (see ToACEWords).

    INTERACTIVELY, use ACEAddRelators (see ACEAddRelators).

  • ds:=list
    Deletes subgroup generators; list must be a list of positive integers.

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

    INTERACTIVELY, use ACEDeleteSubgroupGenerators (see ACEDeleteSubgroupGenerators).

  • dr:=list
    Deletes relators; list must be a list of positive integers.

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

    INTERACTIVELY, use ACEDeleteRelators (see ACEDeleteRelators).

  • cc:=val
    Makes coset val coincide with coset 1; val should be a positive integer.

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

    INTERACTIVELY, use ACECosetCoincidence (see ACECosetCoincidence).

  • rc:=val
  • rc:= [val]
  • rc:= [val, attempts]
    Enforce random coincidences; val and attempts must be positive integers.

    This option attempts upto attempts (or, in the first and second forms, 8) times to find nontrivial subgroups with index a multiple of val by repeatedly making random coset numbers coincident with coset 1 and seeing what happens. The starting coset table must be non-empty, but should not be complete. For each attempt, we repeatedly add random coset representatives to the subgroup and redo the enumeration. If the table becomes too small, the attempt is aborted, the original subgroup generators restored, and another attempt made. If an attempt succeeds, then the new set of subgroup generators is retained.

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

    INTERACTIVELY, use ACERandomCoincidences (see ACERandomCoincidences).

  • D.3 Mode Options

  • mode
    Prints the possible enumeration modes. (Shortest abbreviation: mo.)

    Prints the possible enumeration modes (i.e. which of continu, redo or start are possible (see option continu, option redo and option start).

    INTERACTIVELY, use ACEModes (see ACEModes).

  • begin
  • start
    Start an enumeration. (Shortest abbreviation of begin is beg.)

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

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

    INTERACTIVELY, use ACEStart (see ACEStart).

  • check
  • redo
    Redo an extant enumeration, using the current parameters.

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

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

    INTERACTIVELY, use ACERedo (see ACERedo).

  • continu
    Continues the current enumeration, building upon the existing table. (Shortest abbreviation: cont.)

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

    Note: The ACE standalone allows the option continue, but this is a GAP keyword, and so GAP users must use (mixed-case abbreviations of) continu.

    INTERACTIVELY, use ACEContinue (see ACEContinue).

  • D.4 Options that Interact with the Operating System

  • ai
  • ai:=filename
    Alter input to standard input or filename; filename must be a string.

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

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

  • bye
  • exit
  • qui
    Quit ACE. (Shortest abbreviation of qui is q.)

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

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

    INTERACTIVELY, use ACEQuit (see ACEQuit).

  • system:=string
    Does a shell escape, to execute string; string must be a string. (Shortest abbreviation: sys.)

    Since GAP already provides Exec() for this purpose, this option is unlikely to have a use.

  • D.5 Query Options

  • cycles
    Prints out the table in cycles. (Shortest abbreviation: cy.)

    This option prints out the permutation representation.

    INTERACTIVELY, use ACECycles (see ACECycles).

  • dump
  • dump:=level
  • dump:= [level]
  • dump:= [level, detail]
    Dump the internal variables of ACE; level must be an integer in the range 0 to 2, and detail must be 0 or 1. (Shortest abbreviation: d.)

    The value of level determines which of the three levels of ACE to dump. (You will need to read the standalone manual acce3001.dvi in the standalone-doc directory to understand what Levels 0, 1 and 2 are all about.) The value of detail determines the amount of detail (detail = 0 means less detail). The first form (with no arguments) selects level = 0, detail = 0. The second form of this command makes detail = 0. This option is intended for gurus; the source code should be consulted to see what the output means.

    INTERACTIVELY, use ACEDumpVariables (see ACEDumpVariables).

  • help
    Prints the ACE help screen. (Shortest abbreviation: h.)

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

  • nc
  • nc:=val
  • normal
  • normal:=val
    Check or attempt to enforce normal closure; val must be 0 or 1.

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

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

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

    INTERACTIVELY, use ACEConjugatesForSubgroupNormalClosure (see ACEConjugatesForSubgroupNormalClosure).

  • options
    Dumps version information of the ACE binary. (Shortest abbreviation: opt.)

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

    A typical output, is as follows:

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

    INTERACTIVELY and non-interactively, use the command ACEBinaryVersion(); (see ACEBinaryVersion) for this information, instead, unless you want it in an ACE standalone input file.

  • oo:=val
  • order:=val
    Print a coset representative of a coset number with order a multiple of val modulo the subgroup; val must be an integer.

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

    INTERACTIVELY, use ACEOrders (see ACEOrders), for the case val = 0, or ACEOrder (see ACEOrder), otherwise.

  • sr
  • sr:=val
    Print out parameters of the current presentation; val must be an integer in the range 0 to 5.

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

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

    INTERACTIVELY, use ACEGroupGenerators (see ACEGroupGenerators), ACERelators (see ACERelators), ACESubgroupGenerators (see ACESubgroupGenerators), and ACEParameters (see ACEParameters).

  • print
  • print:=val
  • print:= [val]
  • print:= [val, last]
  • print:= [val, last, by]
    Compact and print the coset table; val must be an integer, and last and by must be positive integers. (Shortest abbreviation: pr.)

    In the first (no value) form, print prints the entire coset table, without orders or coset representatives. In the second and third forms, the absolute value of val is taken to be the last line of the table to be printed (and 1 is taken to be the first); in the fourth and fifth forms, |val| is taken to be the first line of the table to be printed, and last is taken to be the number of the last line to be printed. In the last form, the table is printed from line |val| to line last in steps of by. If val is negative, then the orders modulo the subgroup (if available) and coset representatives are printed also.

    INTERACTIVELY, use ACEDisplayCosetTable (see ACEDisplayCosetTable).

  • sc:=val
  • stabilising:=val
    Print out the coset numbers whose elements normalise the subgroup; val must be an integer. (Shortest abbreviation of stabilising is stabil.)

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

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

    INTERACTIVELY, use ACECosetsThatNormaliseSubgroup (see ACECosetsThatNormaliseSubgroup).

  • statistics
  • stats
    Dump enumeration statistics. (Shortest abbreviation of statistics is stat.)

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

    INTERACTIVELY, use ACEDumpStatistics (see ACEDumpStatistics).

  • style
    Prints the current enumeration style.

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

    INTERACTIVELY, use ACEStyle (see ACEStyle).

  • tw:= [val, word]
  • trace:= [val, word]
    Trace word through the coset table, starting at coset val; val must be a positive integer, and word must be a word in the group generators.

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

    INTERACTIVELY, use ACETraceWord (see ACETraceWord).

  • D.6 Options that Modify the Coset Table

  • recover
  • contiguous
    Recover space used by dead coset numbers. (Shortest abbreviation of recover is reco, and shortest abbreviation of contiguous is contig.)

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

    INTERACTIVELY, use ACERecover (see ACERecover).

  • standard
    Compacts ACE's coset table and standardises the numbering of cosets, according to the lenlex scheme (see Section Coset Table Standardisation Schemes). (Shortest abbreviation: st.)

    For a given ordering of the generators in the columns of the table, it produces a canonical numbering of the cosets. This function does not display the new table; use the print (see option print) for that. Such a table has the property that a scan of the successive rows of the body of the table row by row, from left to right, encounters previously unseen cosets in numeric order.

    Notes: In a lenlex standard table, the coset representatives are ordered first according to length and then the lexicographic order defined by the order the generators and their inverses head the columns. Note that, since ACE avoids having an involutory generator in the first column when it can, this lexicographic order does not necessarily correspond with the order in which the generators were first put to ACE. Two tables are equivalent only if their canonic forms are the same. Invoking this option directly does not affect the GAP coset table obtained via ACECosetTable; use the lenlex (see option lenlex) option, if you want your table lenlex standardised. (The lenlex option restarts the enumeration, if it is necessary to ensure the generators have not been rearranged.)

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

    INTERACTIVELY, use ACEStandardCosetNumbering (see ACEStandardCosetNumbering).

  • D.7 Options for Comments

  • text:=string
    Prints string in the output; string must be a string.

    This allows the user to add comments to the output from ACE.

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

  • aceincomment:=string
    Prints comment string in the ACE input; string must be a string. (Shortest abbreviation: aceinc.)

    This option prints the comment string behind a sharp sign (#) in the input to ACE. Only useful for adding comments (that ACE ignores) to standalone input files.

  • [Up] [Previous] [Index]

    ACE manual
    January 2023