[Up] [Next] [Index]

1 The ACE Package

Sections

  1. Using ACE as a Default for Coset Enumerations
  2. Using ACE Directly to Generate a Coset Table
  3. Using ACE Directly to Test whether a Coset Enumeration Terminates
  4. Writing ACE Standalone Input Files to Generate a Coset Table
  5. Using ACE Interactively
  6. Accessing ACE Examples with ACEExample and ACEReadResearchExample
  7. General Warnings regarding the Use of Options
  8. The ACEData Record
  9. Setting the Verbosity of ACE via Info and InfoACE
  10. Acknowledgements
  11. Changes from earlier versions

The ``Advanced Coset Enumerator'' ACE:

ACE coset enumerator (C) 1995-2001 by George Havas and Colin Ramsay
http://staff.itee.uq.edu.au/havas

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 Installing the ACE Package for how to install ACE). It will not work on Windows. The current version requires at least GAP 4.4.

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

Note: Some care needs to be taken with options; be sure to read Section General Warnings regarding the Use of Options and the introductory sections of Chapter Options for ACE 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.

1.1 Using ACE as a Default for Coset Enumerations

After loading ACE (see Section Loading the ACE Package), 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 TCENUM to ACETCENUM.

gap> TCENUM:=ACETCENUM;;

This sets the function CosetTableFromGensAndRels (see Section Coset Tables and Coset Enumeration in the GAP Reference Manual) to be the function ACECosetTableFromGensAndRels (described in Section Using ACE Directly to Generate a Coset Table), which then can be called with all the options defined for the ACE interface, not just the options max and silent. If TCENUM is set to ACETCENUM without any further action, the default strategy (option) of the ACE enumerator will be used (see Chapter Strategy Options for ACE). This and other options can be modified in the ways described in Chapter Options for ACE. For instance,

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

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 TCENUM to GAPTCENUM.

gap> TCENUM:=GAPTCENUM;;

1.2 Using ACE Directly to Generate a Coset Table

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 General Warnings regarding the Use of Options. The functions discussed in this and the following section (ACECosetTableFromGensAndRels and ACEStats) 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 Using ACE Interactively and Chapter Functions for Using ACE Interactively.

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

  • ACECosetTableFromGensAndRels( fgens, rels, sgens [: options] ) F
  • ACECosetTable( fgens, rels, sgens [: options] ) F

    Here fgens is a list of free generators, rels a list of words in these generators giving relators for a finitely presented group, and sgens the list of subgroup generators, again expressed as words in the free generators. All these are given in the standard GAP format (see Chapter Finitely Presented Groups of the GAP Reference Manual). Note that the 3-argument form of ACECosetTable described here is merely a synonym for ACECosetTableFromGensAndRels, and that ACECosetTable may be called in a different way in an interactive ACE session (see Sections Using ACE Interactively and ACECosetTable!interactive).

    Behind the colon any selection of the options available for the interface (see Chapters Options for ACE and Strategy Options for ACE) 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 Options for ACE, all at once.

    Please see Section General Warnings regarding the Use of Options for a discussion regarding global and local passing of options, and the non-orthogonal nature of ACE's options.

    Each of ACECosetTableFromGensAndRels and ACECosetTable 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: lenlex and semilenlex (see Section Coset Table Standardisation Schemes). The user may control which standardisation scheme is used by selecting either the lenlex (see option lenlex) or semilenlex (see option semilenlex) option; otherwise the table is standardised according to GAP's the value of CosetTableStandard (which by default is lenlex). We provide IsACEStandardCosetTable (see IsACEStandardCosetTable) 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. lenlex or semilenlex) to another standardisation scheme.

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

    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 Fun with ACEExample. Observe that in the example, no options are passed, which means that ACE uses the default strategy (see Chapter Strategy Options for ACE).

    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]);;
    
    

    In computing the coset table, ACECosetTableFromGensAndRels must first do a coset enumeration (which is where ACE comes in!). If the coset enumeration does not finish in the preset limits a break-loop is entered, unless the incomplete (see option incomplete) or silent (see option silent) options is set. In the event that a break-loop is entered, don't despair or be frightened by the word Error; by tweaking ACE's options via the SetACEOptions function that becomes available in the break-loop and then typing return; 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 break-loop again, and you can have another go (or quit; 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 (:) with record components syntax). Let's continue the Fibonacci example above, redoing the last command but with the option max := 2 (see option max), 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 break-loop.

    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 ] ]
    
    

    Observe how the lines after the ``Entering break read-eval-print loop'' announcement tell you exactly what to do. At the break-loop prompt brk> we relaxed all restrictions on max (by re-setting it to 0) and typed return; to leave the break-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 InfoACE (see SetInfoACELevel) to 2, so that the ACE enumeration result is printed.

    gap> SetInfoACELevel(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 ] ]
    
    

    The enumeration result line is the Info line beginning ``#I ''. Appendix The Meanings of ACE's Output Messages explains how to interpret such output messages from ACE. In particular, it explains that t=3127 tells us that a total 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 purec strategy (see option purec):

    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 ] ]
    
    

    ACE needs to define a total number of only (relatively-speaking) 332 coset numbers before the final collapse to 1 coset number.

    Notes: To initiate the coset enumeration, the start option (see option start) is quietly inserted after the user's supplied options, unless the user herself supplies one of the enumeration-invoking options, which are: start, or one of its synonyms, aep (see option aep) or rep (see option rep).

    When a user calls ACECosetTable with the lenlex option (see option lenlex), occasionally it is necessary to enforce asis=1 (see option asis), 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 gens and rels of ACECosetTable, IsACEGeneratorsInPreferredOrder would return false.

    The non-interactive ACECosetTable and ACECosetTableFromGensAndRels 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 ACECosetTable or ACECosetTableFromGensAndRels (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 ACECosetTable and ACEStats (see ACECosetTable!interactive and ACEStats!interactive), together with ACEStart 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 fgens, rels and sgens; the two special forms of ACEStart used, allow one to continually re-use a single interactive ACE process (i.e. only one iostream is used).

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

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

  • IsACEStandardCosetTable( table [: option] ) F

    returns true if table (a list of lists of integers) is standard according to GAP's default or the option (either lenlex or semilenlex) standardisation scheme, or false otherwise. See Section Coset Table Standardisation Schemes for a detailed discussion of the lenlex and semilenlex standardisation schemes.

    Note: Essentially, IsACEStandardCosetTable extends the GAP function IsStandardized.

    Users who wish their coset tables to use ACECosetTable with the lenlex (see option lenlex) option, which causes lenlex standardisation to occur at the ACE (rather than GAP) level, should be aquainted with the following function.

  • IsACEGeneratorsInPreferredOrder( gens, rels ) F

    returns true if gens, 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 rels is a list of relators (i.e. words in the generators gens). IsACEGeneratorsInPreferredOrder may also be called in a different way for interactive ACE processes (see IsACEGeneratorsInPreferredOrder!interactive).

    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. IsACEGeneratorsInPreferredOrder returns true if the order of the generators gens would not be changed within ACE and false, otherwise. (Technically, by ``involution'' above, we really mean ``a generator x for which there is a relator in rels of form x*x or x^2''. Such a generator may, of course, turn out to actually be the identity.)

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

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

    1.3 Using ACE Directly to Test whether a Coset Enumeration Terminates

    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

  • ACEStats( fgens, rels, sgens [: options] ) F

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

     index
    the index of the subgroup 〈sgens 〉 in 〈fgens | rels 〉, or 0 if the enumeration does not succeed;

     cputime
    the total CPU time used as an integer number of cputimeUnits (the next field);

     cputimeUnits
    the units of the cputime field, e.g. "10^-2 seconds";

     activecosets
    the number of currently active (i.e. alive) coset numbers (see Section Coset Statistics Terminology);

     maxcosets
    the maximum number of alive coset numbers at any one time in the enumeration (see Section Coset Statistics Terminology); and

     totcosets
    the total number of coset numbers that were defined in the enumeration (see Section Coset Statistics Terminology).

    Options (see Chapters Options for ACE and Strategy Options for ACE) are used in exactly the same way as for ACECosetTableFromGensAndRels, discussed in the previous section; and the same warnings alluded to previously, regarding options (see Section General Warnings regarding the Use of Options), apply.

    Notes: To initiate the coset enumeration, the start option (see option start) is quietly inserted after the user's supplied options, unless the user herself supplies one of the enumeration-invoking options, which are: start, or one of its synonyms, aep (see option aep) or rep (see option rep).

    The fields of the ACEStats record are determined by parsing a ``results message'' (see Appendix The Meanings of ACE's Output Messages) from ACE.

    ACEStats may also be called in a different way in an interactive ACE session (see ACEStats!interactive).

    1.4 Writing ACE Standalone Input Files to Generate a Coset Table

    If you want to use ACE as a standalone with its own syntax, you can write an ACE standalone input file by calling ACECosetTable with three arguments (see ACECosetTableFromGensAndRels) and the option aceinfile := filename (see option aceinfile). This will keep the input file for the ACE standalone produced by the GAP interface under the file name filename (and just return) so that you can perform interactive work in the standalone.

    1.5 Using ACE Interactively

    An interactive ACE process is initiated with the command

  • ACEStart( fgens, rels, sgens [:options] ) F

    whose arguments and options are exactly as for ACECosetTableFromGensAndRels and ACEStats, as discussed in Sections Using ACE Directly to Generate a Coset Table and Using ACE Directly to Test whether a Coset Enumeration Terminates. The usual warnings regarding options apply (see Section General Warnings regarding the Use of Options). ACEStart has a number of other forms (see ACEStart!details).

    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

  • ACEQuit( i ) F

    where i is the integer returned by ACEStart when the process was begun. ACEQuit may also be called with no arguments (see ACEQuit!details).

    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 Functions for Using ACE interactively.

    Note:

    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 ACEAddSubgroupGenerators (see ACEAddSubgroupGenerators) or implicitly by introducing coincidences (see ACECosetCoincidence: ACECosetCoincidence, or ACERandomCoincidences: ACERandomCoincidences); or one can find smaller subgroups by deleting subgroup generators via ACEDeleteSubgroupGenerators (see ACEDeleteSubgroupGenerators).

    1.6 Accessing ACE Examples with ACEExample and ACEReadResearchExample

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

  • ACEExample() F
  • ACEExample( examplename [:options] ) F
  • ACEExample( examplename, ACEfunc [:options] ) F

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

    If ACEExample is called with no arguments, or with the argument: "index" (meant in the sense of ``list''), or with a non-existent example name, a list of available examples is displayed. See Section Fun with ACEExample where the list is displayed.

    By default, examples are executed via ACEStats. However, if ACEExample is called with a second argument (choose from the (other) alternatives: ACECosetTableFromGensAndRels (or, equivalently ACECosetTable), or ACEStart), 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 ACECosetTable, one would type: ACEExample("A5", ACECosetTable);.

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

    Consider the example "A5". The effect of running

    gap> ACEExample("A5", ACEStart);
    
    

    is essentially equivalent to executing:

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

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

    Please see Section Fun with ACEExample for some sample interactions with ACEExample.

    Notes

    Most examples use the mess ( = messages) option. To see the effect of this, it is recommended to do: SetInfoACELevel(3); before calling ACEExample, with an example.

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

    Also, try SetInfoACELevel(2); before calling ACEExample, with an example.

    If you unexpectedly observe aceexampleoptions in your output, then most probably you have unintentionally passed options by the global method, by having a non-empty OptionsStack. One possible remedy is to use FlushOptionsStack(); (see FlushOptionsStack), before trying your ACEExample call again.

    As discussed in Section Interpretation of ACE Options, there is generally no sensible meaning that can be attributed to setting a strategy option (see Chapter Strategy Options for ACE) to false; if you wish to nullify the effect of a strategy option, pass another strategy option, e.g. pass the default (see option default) strategy option.

    Also provided are:

  • ACEReadResearchExample( filename ) F
  • ACEReadResearchExample() F

    which perform Read (see Section Read in the GAP Reference Manual) on filename or, with no argument, the file with filename "pgrelfind.g" in the res-examples directory; e.g. the effect of running

    gap> ACEReadResearchExample("pgrelfind.g");
    
    

    is equivalent to executing:

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

    The examples provided in the res-examples directory were used to solve a genuine research problem, the results of which are reported in CHHR01. Please see Section Using ACEReadResearchExample for a detailed description and examples of its use.

  • ACEPrintResearchExample( example-filename ) F
  • ACEPrintResearchExample( example-filename, output-filename) F

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

    1.7 General Warnings regarding the Use of Options

    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 Options for ACE all at once. The strategy options are discussed in their own chapter (Chapter Strategy Options for ACE).

    In Section Passing ACE Options, we describe the two means provided by GAP by which ACE options may be passed. In Section Warnings regarding Options, 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 FlushOptionsStack (see FlushOptionsStack). However, removing OptionsStack options does not remove the options previously passed to an interactive ACE process; Section Warnings regarding Options 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 Abbreviations and mixed case for ACE Options). Secondly, since ACE's options are in general not orthogonal, the order in which they are put to ACE is, in general, honoured (see Honouring of the order in which ACE Options are passed). Thirdly, the ACE binary's concept of a boolean option is slightly different to that of GAP's; Section Interpretation of ACE Options discusses, in particular, how an option detected by GAP as true is passed to the ACE binary.

    Finally, Section What happens if no ACE Strategy Option or if no ACE Option is passed discusses what happens if no option is selected.

    1.8 The ACEData Record

  • ACEData V

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

     binary
    the path of the ACE binary;

     tmpdir
    the path of the temporary directory containing the non-interactive ACE input and output files (also see ACEDirectoryTemporary below);

     ni
    the data record for a non-interactive ACE process;

     io
    list of data records for ACEStart (see below and ACEStart) processes;

     infile
    the full path of the ACE input file;

     outfile
    the full path of the ACE output file; and

     version
    the version of the current ACE binary. More detailed information regarding the compilation of the binary is given by ACEBinaryVersion (see ACEBinaryVersion).

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

    Each time an interactive ACE process is initiated via ACEStart (see ACEStart), an identifying number ioIndex is generated for the interactive process and a record ACEData.io[ioIndex] with the following fields is created. A non-interactive process has similar fields but is stored in the record ACEData.ni.

     procId
    the identifying number of the process (ioIndex for interactive processes, and 0 for a non-interactive process);

     args
    a record with fields: fgens, rels, sgens whose values are the corresponding arguments passed originally to ACEStart;

     options
    the current options record of the interactive process;

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

     stream
    the IOStream opened for an interactive ACE process initiated via ACEStart; and

     enumResult
    the enumeration result (string) without the trailing newline, output from ACE;

     stats
    a record as output by the function ACEStats.

     enforceAsis
    a boolean that is set to true whenever the asis option (see option asis) must be set to 1. It is usually false. See IsACEGeneratorsInPreferredOrder Guru Notes for the details.

  • ACEDirectoryTemporary( dir ) F

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

    1.9 Setting the Verbosity of ACE via Info and InfoACE

  • InfoACE V

    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 Info mechanism (see Chapter Info Functions in the GAP Reference Manual). For this purpose, there is the InfoClass InfoACE. Each line of output from ACE is directed to a call to Info and will be displayed for the user to see if the InfoLevel of InfoACE is high enough. By default, the InfoLevel of InfoACE 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 Info at InfoACE level 1. To turn off all InfoACE messaging, set the InfoACE level to 0 (see SetInfoACELevel). For convenience, we provide the function

  • InfoACELevel() F

    which returns the current InfoLevel of InfoACE, i.e. it is simply a shorthand for InfoLevel(InfoACE).

    To set the InfoLevel of InfoACE we also provide

  • SetInfoACELevel( level ) F
  • SetInfoACELevel() F

    which for a non-negative integer level, sets the InfoLevel of InfoACE to level (i.e. it is a shorthand for SetInfoLevel(InfoACE, level)), or with no arguments sets the InfoACE level to the default value 1. Currently, information from ACE is directed to Info at four InfoACE levels: 1, 2, 3 and 4. The command

    gap> SetInfoACELevel(2);
    
    

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

    gap> SetInfoACELevel(3);
    
    

    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 messages option (see option messages) is set to a non-zero value, will be displayed via Info. Finally,

    gap> SetInfoACELevel(4);
    
    

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

    1.10 Acknowledgements

    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 Ram99ace for the standalone version of ACE by Colin Ramsay. Most of the examples, in the examples directory and accessed via the ACEExample 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 Steering ACE Interactively which demonstrates rather nicely how one can use the function ACEConjugatesForSubgroupNormalClosure.

    We also wish to acknowledge the contribution of Charles Sims. The inclusion of the incomplete (see option incomplete) and lenlex (see option lenlex) options, were made in response to requests to the GAP developers to include such options for coset table functions. Also, the definition of lenlex standardisation of coset tables (see Section Coset Table Standardisation Schemes), 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 GitHub has been due to Max Horn.

    1.11 Changes from earlier versions

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

    The 3.xxx 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 Coset Table Standardisation Schemes).

  • ACEPackageVersion() F

    gives the current version of the ACE Package (i.e. the GAP code component; the function ACEBinaryVersion (see ACEBinaryVersion) gives details of the C code compilation).

    [Up] [Next] [Index]

    ACE manual
    January 2023