In this chapter  we  collect  together  a  number  of  examples  which
illustrate the various ways in which the ACE Package may  be  used,
and give some interactions with the ACEExample function. In a number
of cases, we have set the InfoLevel of InfoACE to 3, so  that  all
output from ACE is displayed, prepended by ``#I  ''. Recall that
to also see the commands directed to ACE (behind a  ``ToACE> ''
prompt), you will need to set  the  InfoACE  level  to  4.  We  have
omitted the line
gap> LoadPackage("ace");
true
which is, of course, required at the beginning of any session requiring ACE.
If ACE is made the standard coset enumerator, one simply  uses  the
method of passing arguments normally used  with  those  commands  that
invoke CosetTableFromGensAndRels, but one is able to use all options
available via the ACE interface. As an example  we  use  ACE  to
compute the permutation representation of a  perfect  group  from  the
data library (GAP's perfect group library stores for each  group  a
presentation together with generators of a subgroup as  words  in  the
group generators such  that  the  permutation  representation  on  the
cosets  of  this  subgroup  will  be  a  (nice)  faithful  permutation
representation for the perfect group). The example we have  chosen  is
an extension of a group of order 16 by the  simple  alternating  group
A5.
gap> TCENUM:=ACETCENUM;; # Make ACE the standard coset enumerator
gap> G := PerfectGroup(IsPermGroup, 16*60, 1   # Arguments ... as per usual
>                      : max := 50, mess := 10 # ... but we use ACE options
>                      );
A5 2^4
gap> GeneratorsOfGroup(G); # Just to show we indeed have a perm'n rep'n
[ (2,4)(3,5)(7,15)(8,14)(10,13)(12,16), (2,6,7)(3,11,12)(4,14,5)(8,9,13)(10,
    15,16), (1,2)(3,8)(4,9)(5,10)(6,7)(11,15)(12,14)(13,16), 
  (1,3)(2,8)(4,13)(5,6)(7,10)(9,16)(11,12)(14,15), 
  (1,4)(2,9)(3,13)(5,14)(6,15)(7,11)(8,16)(10,12), 
  (1,5)(2,10)(3,6)(4,14)(7,8)(9,12)(11,16)(13,15) ]
gap> Order(G);
960
The call to PerfectGroup produced an output string  that  identifies
the group G, but we didn't see  how  ACE  became  involved  here.
Let's redo that part of the above  example  after  first  setting  the
InfoLevel of InfoACE to 3, so that we may get  to  glimpse  what's
going on behind the scenes.
gap> SetInfoACELevel(3); # Just to see what's going on behind the scenes gap> # Recall that we did: TCENUM:=ACETCENUM;; gap> G := PerfectGroup(IsPermGroup, 16*60, 1 # Arguments ... as per usual > : max := 50, mess := 10 # ... but we use ACE options > ); #I ACE 3.001 Sun Sep 30 22:08:11 2001 #I ========================================= #I Host information: #I name = rigel #I *** #I #--- ACE 3.001: Run Parameters --- #I Group Name: G; #I Group Generators: abstuv; #I Group Relators: (a)^2, (s)^2, (t)^2, (u)^2, (v)^2, (b)^3, (st)^2, (uv)^2, #I (su)^2, (sv)^2, (tu)^2, (tv)^2, asau, atav, auas, avat, Bvbu, Bsbvt, #I Bubvu, Btbvuts, (ab)^5; #I Subgroup Name: H; #I Subgroup Generators: a, b; #I Wo:1000000; Max:50; Mess:10; Ti:-1; Ho:-1; Loop:0; #I As:0; Path:0; Row:1; Mend:0; No:21; Look:0; Com:10; #I C:0; R:0; Fi:11; PMod:3; PSiz:256; DMod:4; DSiz:1000; #I #--------------------------------- #I SG: a=1 r=1 h=1 n=2; l=1 c=+0.00; m=1 t=1 #I RD: a=11 r=1 h=1 n=12; l=2 c=+0.00; m=11 t=11 #I RD: a=21 r=2 h=1 n=22; l=2 c=+0.00; m=21 t=21 #I CC: a=29 r=4 h=1 n=31; l=2 c=+0.00; d=0 #I CC: a=19 r=4 h=1 n=31; l=2 c=+0.00; d=0 #I CC: a=19 r=6 h=1 n=36; l=2 c=+0.00; d=0 #I INDEX = 16 (a=16 r=36 h=1 n=36; l=3 c=0.00; m=30 t=35) #I CO: a=16 r=17 h=1 n=17; c=+0.00 #I coset | b B a s t u v #I -------+------------------------------------------------- #I 1 | 1 1 1 2 3 4 5 #I 2 | 11 14 4 1 6 8 9 #I 3 | 13 15 5 6 1 10 11 #I 4 | 7 5 2 8 10 1 7 #I 5 | 4 7 3 9 11 7 1 #I 6 | 8 10 7 3 2 12 14 #I 7 | 5 4 6 15 16 5 4 #I 8 | 10 6 8 4 12 2 15 #I 9 | 16 12 10 5 14 15 2 #I 10 | 6 8 9 12 4 3 16 #I 11 | 14 2 11 14 5 16 3 #I 12 | 9 16 15 10 8 6 13 #I 13 | 15 3 13 16 15 14 12 #I 14 | 2 11 16 11 9 13 6 #I 15 | 3 13 12 7 13 9 8 #I 16 | 12 9 14 13 7 11 10 A5 2^4
The following example calls ACE for up to 800 coset  numbers  (max
:= 800) using Mendelsohn style relator processing (mendelsohn)  and
sets progress messages to be printed every 500  iterations  (messages
:=500); we do ``SetInfoACELevel(3);'' so  that  we  may  see  these
messages.  The  value  of  table,  i.e. the  GAP   coset   table,
immediately follows the last ACE  message  (``#I '')  line,  but
both the coset table from ACE and the GAP coset table have  been
abbreviated. A  slightly  modified  version  of  this  example,  which
includes  the  echo  option  is  available  on-line  via  table  :=
ACEExample("perf602p5");. You may wish to peruse  the  notes  in  the
ACEExample index first, however, by executing ACEExample();. (Note
that the final table output here is lenlex  standardised  (the  case
since GAP 4.3); with GAP 4.2 the final  table  was  semilenlex
standardised.)
gap> SetInfoACELevel(3);           # So we can see the progress messages
gap> G := PerfectGroup(2^5*60, 2);;# See previous example:
gap>                               # "Example where ACE is made the
gap>                               #  Standard Coset Enumerator"
gap> fgens := FreeGeneratorsOfFpGroup(G);;
gap> table := ACECosetTableFromGensAndRels(
>                 # arguments
>                 fgens, RelatorsOfFpGroup(G), fgens{[1]}
>                 # options
>                 : mendelsohn, max:=800, mess:=500);
#I  ACE 3.001        Sun Sep 30 22:10:10 2001
#I  =========================================
#I  Host information:
#I    name = rigel
#I  ***
#I    #--- ACE 3.001: Run Parameters ---
#I  Group Name: G;
#I  Group Generators: abstuvd;
#I  Group Relators: (s)^2, (t)^2, (u)^2, (v)^2, (d)^2, aad, (b)^3, (st)^2, 
#I    (uv)^2, (su)^2, (sv)^2, (tu)^2, (tv)^2, Asau, Atav, Auas, Avat, Bvbu, 
#I    dAda, dBdb, (ds)^2, (dt)^2, (du)^2, (dv)^2, Bubvu, Bsbdvt, Btbvuts, 
#I    (ab)^5;
#I  Subgroup Name: H;
#I  Subgroup Generators: a;
#I  Wo:1000000; Max:800; Mess:500; Ti:-1; Ho:-1; Loop:0;
#I  As:0; Path:0; Row:1; Mend:1; No:28; Look:0; Com:10;
#I  C:0; R:0; Fi:13; PMod:3; PSiz:256; DMod:4; DSiz:1000;
#I    #---------------------------------
#I  SG: a=1 r=1 h=1 n=2; l=1 c=+0.00; m=1 t=1
#I  RD: a=321 r=68 h=1 n=412; l=5 c=+0.00; m=327 t=411
#I  CC: a=435 r=162 h=1 n=719; l=9 c=+0.00; d=0
#I  CL: a=428 r=227 h=1 n=801; l=13 c=+0.00; m=473 t=800
#I  DD: a=428 r=227 h=1 n=801; l=14 c=+0.00; d=33
#I  CO: a=428 r=192 h=243 n=429; l=15 c=+0.00; m=473 t=800
#I  INDEX = 480 (a=480 r=210 h=484 n=484; l=18 c=0.00; m=480 t=855)
#I  CO: a=480 r=210 h=481 n=481; c=+0.00
#I   coset |      a      A      b      B      s      t      u      v      d
#I  -------+---------------------------------------------------------------
#I       1 |      1      1      7      6      2      3      4      5      1
#I       2 |      4      4     22     36      1      8     10     11      2
... 476 lines omitted here ...
#I     479 |    479    479    384    383    475    468    470    471    479
#I     480 |    480    480    421    420    470    469    475    476    480
[ [ 1, 8, 13, 6, 7, 4, 5, 2, 34, 35, 32, 33, 3, 48, 49, 46, 47, 57, 59, 28, 
      21, 25, 62, 64, 22, 26, 66, 20, 67, 69, 74, 11, 12, 9, 10, 89, 65, 87, 
... 30 lines omitted here ...
      477, 438, 478, 446, 475, 479, 471, 473, 476, 469 ], 
  [ 1, 8, 13, 6, 7, 4, 5, 2, 34, 35, 32, 33, 3, 48, 49, 46, 47, 57, 59, 28, 
      21, 25, 62, 64, 22, 26, 66, 20, 67, 69, 74, 11, 12, 9, 10, 89, 65, 87, 
... 30 lines omitted here ...
      477, 438, 478, 446, 475, 479, 471, 473, 476, 469 ], 
... 363 lines omitted here ...
  [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 
      21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 
... 30 lines omitted here ...
      472, 473, 474, 475, 476, 477, 478, 479, 480 ] ]
Now we illustrate a simple interactive process, with an enumeration of
an index 12 subgroup (isomorphic to C5) within A5. Observe  that
we  have  relied  on  the  default  level  of  messaging  from  ACE
(messages = 0) which gives a result line (the  ``#I  INDEX'' line
here) only, without parameter information. The result line is  visible
in the Info-ed component of the output  below  because  we  set  the
InfoLevel of InfoACE to a value of at least 2 (in fact we  set  it
to 3; doing ``SetInfoACELevel(2);'' would  make  only  the  result
line visible). We have however used the option echo, so that we  can
see how the interface handled the arguments and options. On-line  try:
SetInfoACELevel(3); ACEExample("A5-C5", ACEStart); (this  is  nearly
equivalent to the sequence following, but the variables F, a, b,
G are not accessible, being ``local'' to ACEExample).
gap> SetInfoACELevel(3); # So we can see output from ACE binary
gap> F := FreeGroup("a","b");; a := F.1;;  b := F.2;;
gap> G := F / [a^2, b^3, (a*b)^5 ];
<fp group on the generators [ a, b ]>
gap> ACEStart(FreeGeneratorsOfFpGroup(G), RelatorsOfFpGroup(G), [a*b]
>          # Options
>          : echo, # Echo handled by GAP (not ACE)
>            enum := "A_5",  # Give the group G a meaningful name
>            subg := "C_5"); # Give the subgroup a meaningful name
ACEStart called with the following arguments:
 Group generators : [ a, b ]
 Group relators : [ a^2, b^3, a*b*a*b*a*b*a*b*a*b ]
 Subgroup generators : [ a*b ]
#I  ACE 3.001        Sun Sep 30 22:11:42 2001
#I  =========================================
#I  Host information:
#I    name = rigel
ACEStart called with the following options:
 echo := true (not passed to ACE)
 enum := A_5
 subg := C_5
#I  ***
#I  INDEX = 12 (a=12 r=16 h=1 n=16; l=3 c=0.00; m=14 t=15)
1
The return value on the last line is an ``index'' that identifies  the
interactive process; we use this ``index'' with functions that need to
interact with the interactive ACE process; we now demonstrate  this
with the interactive version of ACEStats:
gap> ACEStats(1); rec( index := 12, cputime := 0, cputimeUnits := "10^-2 seconds", activecosets := 12, maxcosets := 14, totcosets := 15 ) gap> # Actually, we didn't need to pass an argument to ACEStats() gap> # ... we could have relied on the default: gap> ACEStats(); rec( index := 12, cputime := 0, cputimeUnits := "10^-2 seconds", activecosets := 12, maxcosets := 14, totcosets := 15 )
Similarly, we may use ACECosetTable with 0 or 1 arguments, which  is
the interactive version of ACECosetTableFromGensAndRels,  and  which
returns a standard table (since GAP 4.3,  a  standard  table  is  a
lenlex standard table;  with  GAP  4.2,  it  was  a  semilenlex
standard table).
gap> ACECosetTable(); # Interactive version of ACECosetTableFromGensAndRels() #I CO: a=12 r=13 h=1 n=13; c=+0.00 #I coset | b B a #I -------+--------------------- #I 1 | 3 2 2 #I 2 | 1 3 1 #I 3 | 2 1 4 #I 4 | 8 5 3 #I 5 | 4 8 6 #I 6 | 9 7 5 #I 7 | 6 9 8 #I 8 | 5 4 7 #I 9 | 7 6 10 #I 10 | 12 11 9 #I 11 | 10 12 12 #I 12 | 11 10 11 [ [ 2, 1, 4, 3, 7, 8, 5, 6, 10, 9, 12, 11 ], [ 2, 1, 4, 3, 7, 8, 5, 6, 10, 9, 12, 11 ], [ 3, 1, 2, 5, 6, 4, 8, 9, 7, 11, 12, 10 ], [ 2, 3, 1, 6, 4, 5, 9, 7, 8, 12, 10, 11 ] ] gap> # To terminate the interactive process we do: gap> ACEQuit(1); # Again, we could have omitted the 1 gap> # If we had more than one interactive process we could have gap> # terminated them all in one go with: gap> ACEQuitAll();
First let's see the ACEExample index  (obtained  with  no  argument,
with  "index"  as  argument,  or  with  a  non-existent  example  as
argument):
gap> ACEExample();
#I                   ACEExample Index (Table of Contents)
#I                   ------------------------------------
#I  This table of possible examples is displayed when calling ACEExample 
#I  with no arguments, or with the argument: "index" (meant in the sense
#I  of `list'), or with a non-existent example name.
#I  
#I  The following ACE examples are available (in each case, for a subgroup
#I  H of a group G, the cosets of H in G are enumerated):
#I  
#I    Example          G                      H              strategy
#I    -------          -                      -              --------
#I    "A5"             A_5                    Id             default
#I    "A5-C5"          A_5                    C_5            default
#I    "C5-fel0"        C_5                    Id             felsch := 0
#I    "F27-purec"      F(2,7) = C_29          Id             purec
#I    "F27-fel0"       F(2,7) = C_29          Id             felsch := 0
#I    "F27-fel1"       F(2,7) = C_29          Id             felsch := 1
#I    "M12-hlt"        M_12 (Matthieu group)  Id             hlt
#I    "M12-fel1"       M_12 (Matthieu group)  Id             felsch := 1
#I    "SL219-hard"     SL(2,19)               |G : H| = 180  hard
#I    "perf602p5"      PerfectGroup(60*2^5,2) |G : H| = 480  default
#I  * "2p17-fel1"      |G| = 2^17             Id             felsch := 1
#I    "2p17-fel1a"     |G| = 2^17             |G : H| = 1    felsch := 1
#I    "2p17-2p3-fel1"  |G| = 2^17             |G : H| = 2^3  felsch := 1
#I    "2p17-2p14-fel1" |G| = 2^17             |G : H| = 2^14 felsch := 1
#I    "2p17-id-fel1"   |G| = 2^17             Id             felsch := 1
#I  * "2p18-fel1"      |G| = 2^18             |G : H| = 2    felsch := 1
#I  * "big-fel1"       |G| = 2^18.3           |G : H| = 6    felsch := 1
#I  * "big-hard"       |G| = 2^18.3           |G : H| = 6    hard
#I  
#I  Notes
#I  -----
#I  1. The example (first) argument of ACEExample() is a string; each
#I     example above is in double quotes to remind you to include them.
#I  2. By default, ACEExample applies ACEStats to the chosen example. You 
#I     may alter the ACE function used, by calling ACEExample with a 2nd 
#I     argument; choose from: ACECosetTableFromGensAndRels (or, equival-
#I     ently ACECosetTable), or ACEStart, e.g. `ACEExample("A5", ACEStart);'
#I  3. You may call ACEExample with additional ACE options (entered after a
#I     colon in the usual way for options), e.g. `ACEExample("A5" : hlt);' 
#I  4. Try the *-ed examples to explore how to modify options when an
#I     enumeration fails (just follow the instructions you get within the
#I     break-loop, or see Notes 2. and 3.).
#I  5. Try `SetInfoACELevel(3);' before calling ACEExample, to see the
#I     effect of setting the "mess" (= "messages") option.
#I  6. To suppress a long output, use a double semicolon (`;;') after the
#I     ACEExample command. (However, this does not suppress Info-ed output.)
#I  7. Also, try `SetInfoACELevel(2);' or `SetInfoACELevel(4);' before 
#I     calling ACEExample.
gap> 
Notice that the example we first met in Section Using ACE Directly to Generate a Coset Table, the Fibonacci group F(2,7), is available  via
examples  "F27-purec",  "F27-fel0",  and  "F27-fel1"  (with  2nd
argument ACECosetTableFromGensAndRels to  produce  a  coset  table),
except that each of these enumerate the cosets of its trivial subgroup
(of index 29).  Let's  experiment  with  the  first  of  these  F(2,7)
examples; since this example uses the messages option, we  ought  to
set the InfoLevel of InfoACE to 3,  first,  but  since  the  coset
table is quite long, we will be content for the moment  with  applying
the default function ACEStats to the example.
Before exhibiting the example we list a few observations  that  should
be made. Observe that  the  first  group  of  Info  lines  list  the
commands that are executed; these lines are followed by the result  of
the echo option (see option echo); which in turn are  followed  by
Info messages from ACE courtesy of  the  non-zero  value  of  the
messages  option  (and  we  see  these  because  we  first  set  the
InfoLevel of InfoACE  to  3);  and  finally,  we  get  the  output
(record) of the ACEStats command.
Observe also that ACE uses the same generators as  are input;  this
will always occur if you stick to single lowercase  letters  for  your
generator names. Note, also that capitalisation is used by ACE as a
short-hand for inverses, e.g. C = c^-1 (see Group Relators in  the
ACE ``Run Parameters'' block).
gap> SetInfoACELevel(3);
gap> ACEExample("F27-purec");
#I  # ACEExample "F27-purec" : enumeration of cosets of H in G,
#I  # where G = F(2,7) = C_29, H = Id, using purec strategy.
#I  #
#I  # F, G, a, b, c, d, e, x, y are local to ACEExample
#I  # We define F(2,7) on 7 generators
#I  F := FreeGroup("a","b","c","d","e", "x", "y"); 
#I       a := F.1;  b := F.2;  c := F.3;  d := F.4; 
#I       e := F.5;  x := F.6;  y := F.7;
#I  G := F / [a*b*c^-1, b*c*d^-1, c*d*e^-1, d*e*x^-1, 
#I            e*x*y^-1, x*y*a^-1, y*a*b^-1];
#I  ACEStats(
#I      FreeGeneratorsOfFpGroup(G), 
#I      RelatorsOfFpGroup(G), 
#I      [] # Generators of identity subgroup (empty list)
#I      # Options that don't affect the enumeration
#I      : echo, enum := "F(2,7), aka C_29", subg := "Id", 
#I      # Other options
#I      wo := "2M", mess := 25000, purec);
ACEStats called with the following arguments:
 Group generators : [ a, b, c, d, e, x, y ]
 Group relators : [ 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 ]
 Subgroup generators : [  ]
#I  ACE 3.001        Sun Sep 30 22:16:08 2001
#I  =========================================
#I  Host information:
#I    name = rigel
ACEStats called with the following options:
 echo := true (not passed to ACE)
 enum := F(2,7), aka C_29
 subg := Id
 wo := 2M
 mess := 25000
 purec (no value, passed to ACE via option: pure c)
#I  ***
#I    #--- ACE 3.001: Run Parameters ---
#I  Group Name: F(2,7), aka C_29;
#I  Group Generators: abcdexy;
#I  Group Relators: abC, bcD, cdE, deX, exY, xyA, yaB;
#I  Subgroup Name: Id;
#I  Subgroup Generators: ;
#I  Wo:2M; Max:142855; Mess:25000; Ti:-1; Ho:-1; Loop:0;
#I  As:0; Path:0; Row:0; Mend:0; No:0; Look:0; Com:100;
#I  C:1000; R:0; Fi:1; PMod:0; PSiz:256; DMod:4; DSiz:1000;
#I    #---------------------------------
#I  DD: a=5290 r=1 h=1050 n=5291; l=8 c=+0.00; d=2
#I  CD: a=10410 r=1 h=2149 n=10411; l=13 c=+0.01; m=10410 t=10410
#I  DD: a=15428 r=1 h=3267 n=15429; l=18 c=+0.01; d=0
#I  DD: a=20430 r=1 h=4386 n=20431; l=23 c=+0.02; d=1
#I  DD: a=25397 r=1 h=5519 n=25399; l=28 c=+0.01; d=1
#I  CD: a=30313 r=1 h=6648 n=30316; l=33 c=+0.01; m=30313 t=30315
#I  DS: a=32517 r=1 h=7326 n=33240; l=36 c=+0.01; s=2000 d=997 c=4
#I  DS: a=31872 r=1 h=7326 n=33240; l=36 c=+0.00; s=4000 d=1948 c=53
#I  DS: a=29077 r=1 h=7326 n=33240; l=36 c=+0.00; s=8000 d=3460 c=541
#I  DS: a=23433 r=1 h=7326 n=33240; l=36 c=+0.01; s=16000 d=5940 c=2061
#I  DS: a=4163 r=1 h=7326 n=33240; l=36 c=+0.03; s=32000 d=447 c=15554
#I  INDEX = 29 (a=29 r=1 h=33240 n=33240; l=37 c=0.15; m=33237 t=33239)
rec( index := 29, cputime := 15, cputimeUnits := "10^-2 seconds", 
  activecosets := 29, maxcosets := 33237, totcosets := 33239 )
Now let's see that we  can  add  some  new  options,  even  ones  that
over-ride the example's options; but first we'll reduce the  output  a
bit by setting the InfoLevel of InfoACE to 2 and since we are  not
going to observe any progress messages from ACE with that InfoACE
level  we'll  set  messages  :=  0;  also  we'll  use  the  function
ACECosetTableFromGensAndRels and so it's like  our  first  encounter
with F(2,7) we'll add the subgroup generator c  via  sg  :=  ["c"]
(see option sg). Observe that "c" is a string not a  GAP  group
generator; to convert a list of GAP  words  sgens  in  generators
fgens, suitable for  an  assignment  of  the  sg  option  use  the
construction: ToACEWords(fgens, sgens) (see ToACEWords).  Note
again that if  only  single  lowercase  letter  strings  are  used  to
identify the GAP group generators, the same  strings  are  used  to
identify those generators in ACE. (It's actually fortunate that  we
could pass the value of sg as a string here, since the generators of
each ACEExample  example  are  local  variables  and  so  are  not
accessible, though  we  could  call  ACEExample  with  2nd  argument
ACEStart and use ACEGroupGenerators to  get  at  them.)  For  good
measure, we also change the string identifying the subgroup (since  it
will no longer be the trivial group), via the subgroup  option  (see
option subgroup).
In considering the example following, observe that in the Info block
all the original example options are listed along with our new options
sg := [ "c" ], messages := 0 after the tag  ``#  User  Options''.
Following the Info block there is a block  due  to  echo;  in  its
listing of the options first up there is aceexampleoptions  alerting
us that we passed some ACEExample options; observe also that in this
block subg := Id and mess := 25000 disappear (they are over-ridden
by subgroup := "< c >", messages := 0, but the quotes for the value
of subgroup are not visible); note that we don't  have  to  use  the
same abbreviations for options to over-ride them.  Also  observe  that
our new options are last.
gap> SetInfoACELevel(2);
gap> ACEExample("F27-purec", ACECosetTableFromGensAndRels
>               : sg := ["c"], subgroup := "< c >", messages := 0);
#I  # ACEExample "F27-purec" : enumeration of cosets of H in G,
#I  # where G = F(2,7) = C_29, H = Id, using purec strategy.
#I  #
#I  # F, G, a, b, c, d, e, x, y are local to ACEExample
#I  # We define F(2,7) on 7 generators
#I  F := FreeGroup("a","b","c","d","e", "x", "y"); 
#I       a := F.1;  b := F.2;  c := F.3;  d := F.4; 
#I       e := F.5;  x := F.6;  y := F.7;
#I  G := F / [a*b*c^-1, b*c*d^-1, c*d*e^-1, d*e*x^-1, 
#I            e*x*y^-1, x*y*a^-1, y*a*b^-1];
#I  ACECosetTableFromGensAndRels(
#I      FreeGeneratorsOfFpGroup(G), 
#I      RelatorsOfFpGroup(G), 
#I      [] # Generators of identity subgroup (empty list)
#I      # Options that don't affect the enumeration
#I      : echo, enum := "F(2,7), aka C_29", subg := "Id", 
#I      # Other options
#I      wo := "2M", mess := 25000, purec, 
#I      # User Options
#I        sg := [ "c" ],
#I        subgroup := "< c >",
#I        messages := 0);
ACECosetTableFromGensAndRels called with the following arguments:
 Group generators : [ a, b, c, d, e, x, y ]
 Group relators : [ 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 ]
 Subgroup generators : [  ]
ACECosetTableFromGensAndRels called with the following options:
 aceexampleoptions := true (inserted by ACEExample, not passed to ACE)
 echo := true (not passed to ACE)
 enum := F(2,7), aka C_29
 wo := 2M
 purec (no value, passed to ACE via option: pure c)
 sg := [ "c" ] (brackets are not passed to ACE)
 subgroup := < c >
 messages := 0
#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 ] ]
Now following on from our last example we shall  demonstrate  how  one
can recover from a break-loop (see Section Using  ACE  Directly  to Generate a Coset Table). To force the break-loop we pass max := 2
(see option  max),  while  using  the  ACE   interface   function
ACECosetTableFromGensAndRels with ACEExample; in this way,  ACE
will not be able to complete  the  enumeration,  and  hence  enters  a
break-loop when it tries to provide a complete  coset  table.  While
we're at it we'll pass the hlt (see option  hlt)  strategy  option
(which will over-ride purec). (The InfoACE level is still  2.)  To
avoid getting a trace-back during the break-loop (which can  look  a
little   scary   to   the   unitiated)   we   will    set    OnBreak
(see OnBreak) as follows:
gap> NormalOnBreak := OnBreak;; # Save the old value to restore it later gap> OnBreak := function() Where(0); end;;
Note that there are  some  ``user-input''  comments  inserted  at  the
brk> prompt.
gap> ACEExample("F27-purec", ACECosetTableFromGensAndRels
>               : sg := ["c"], subgroup := "< c >", max := 2, hlt);
#I  # ACEExample "F27-purec" : enumeration of cosets of H in G,
#I  # where G = F(2,7) = C_29, H = Id, using purec strategy.
#I  #
#I  # F, G, a, b, c, d, e, x, y are local to ACEExample
#I  # We define F(2,7) on 7 generators
#I  F := FreeGroup("a","b","c","d","e", "x", "y"); 
#I       a := F.1;  b := F.2;  c := F.3;  d := F.4; 
#I       e := F.5;  x := F.6;  y := F.7;
#I  G := F / [a*b*c^-1, b*c*d^-1, c*d*e^-1, d*e*x^-1, 
#I            e*x*y^-1, x*y*a^-1, y*a*b^-1];
#I  ACECosetTableFromGensAndRels(
#I      FreeGeneratorsOfFpGroup(G), 
#I      RelatorsOfFpGroup(G), 
#I      [] # Generators of identity subgroup (empty list)
#I      # Options that don't affect the enumeration
#I      : echo, enum := "F(2,7), aka C_29", subg := "Id", 
#I      # Other options
#I      wo := "2M", mess := 25000, purec, 
#I      # User Options
#I        sg := [ "c" ],
#I        subgroup := "< c >",
#I        max := 2,
#I        hlt := true);
ACECosetTableFromGensAndRels called with the following arguments:
 Group generators : [ a, b, c, d, e, x, y ]
 Group relators : [ 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 ]
 Subgroup generators : [  ]
ACECosetTableFromGensAndRels called with the following options:
 aceexampleoptions := true (inserted by ACEExample, not passed to ACE)
 echo := true (not passed to ACE)
 enum := F(2,7), aka C_29
 wo := 2M
 mess := 25000
 purec (no value, passed to ACE via option: pure c)
 sg := [ "c" ] (brackets are not passed to ACE)
 subgroup := < c >
 max := 2
 hlt (no value)
#I  OVERFLOW (a=2 r=1 h=1 n=3; l=4 c=0.00; m=2 t=2)
Error, no coset table ...
 the `ACE' coset enumeration failed with the result:
 OVERFLOW (a=2 r=1 h=1 n=3; l=4 c=0.00; m=2 t=2)
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> # Let's give ACE enough coset numbers to work with ...
brk> # and while we're at it see the effect of 'echo := 2' :
brk> SetACEOptions(: max := 0, echo := 2);
brk> # Let's check what the options are now:
brk> DisplayACEOptions();
rec(
  enum := "F(2,7), aka C_29",
  wo := "2M",
  mess := 25000,
  purec := true,
  sg := [ "c" ],
  subgroup := "< c >",
  hlt := true,
  max := 0,
  echo := 2 )
brk> # That's ok ... so now we 'return;' to escape the break-loop
brk> return;
ACECosetTableFromGensAndRels called with the following arguments:
 Group generators : [ a, b, c, d, e, x, y ]
 Group relators : [ 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 ]
 Subgroup generators : [  ]
ACECosetTableFromGensAndRels called with the following options:
 enum := F(2,7), aka C_29
 wo := 2M
 mess := 25000
 purec (no value, passed to ACE via option: pure c)
 sg := [ "c" ] (brackets are not passed to ACE)
 subgroup := < c >
 hlt (no value)
 max := 0
 echo := 2 (not passed to ACE)
Other options set via ACE defaults:
 asis := 0
 compaction := 10
 ct := 0
 dmode := 0
 dsize := 1000
 fill := 1
 hole := -1
 lookahead := 1
 loop := 0
 mendelsohn := 0
 no := 0
 path := 0
 pmode := 0
 psize := 256
 row := 1
 rt := 1000
 time := -1
#I  INDEX = 1 (a=1 r=2 h=2 n=2; l=3 c=0.00; m=2049 t=3127)
[ [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], 
  [ 1 ], [ 1 ], [ 1 ], [ 1 ] ]
Observe that  purec  did  not  disappear  from  the  option  list;
nevertheless, it is over-ridden by the hlt option (at  the  ACE
level). Observe the  ``Other options set via ACE defaults'' list  of
options  that  has  resulted  from  having  the  echo  :=  2  option
(see option echo). Observe, also, that  hlt  is  nowhere  near  as
good, here, as  purec  (refer  to  Section Using  ACE  Directly  to Generate  a  Coset  Table):  whereas  purec  completed   the   same
enumeration with a total number of coset numbers  of  332,  the  hlt
strategy required 3127.
Before we finish this section, let us say something about the examples
listed when one calls ACEExample with no arguments that have  a  *
beside them; these are examples for which  the  enumeration  fails  to
complete. The first such example  listed  is  "2p17-fel1",  where  a
group of order 217 is enumerated over the identity subgroup  with
the felsch := 1 strategy. The enumeration  fails  after  defining  a
total number of 416664 coset numbers. (In fact, the enumeration can be
made to succeed by simply increasing workspace to "4700k", but  in
doing so a total of  783255  coset  numbers  are  defined.)  With  the
example "2p17-fel1a" the same group is again enumerated, again  with
the felsch := 1 strategy, but this time over the  group  itself  and
after tweaking a few options, to see how well we  can  do.  The  other
"2p17-XXX" examples are again enumerations of the same  group  but
over smaller and smaller subgroups, until we once again enumerate over
the identity subgroup but far more efficiently this time (only needing
to define a total of 550659 coset numbers, which can be achieved  with
workspace set to "3300k").
The other *-ed examples enumerate overgroups of the group  of  order
217 of the "2p17-XXX" examples. It's recommended that you try
these with second argument ACECosetTableFromGensAndRels so that  you
enter a break-loop, where you  can  experiment  with  modifying  the
options using SetACEOptions. The example "2p18-fel1" can  be  made
to succeed with hard, mend, workspace := "10M"; why don't you see if
you can do better! There  are  no  hints  for  the  other  two  *-ed
examples; they are exercises for you to try.
Let's now restore the original value of OnBreak:
gap> OnBreak := NormalOnBreak;;
Of course, running ACEExample with  ACEStart  as  second  argument
opens up far more flexibility. Try it! Have fun!  Play  with  as  many
options as you can. 
Without an argument, the function ACEReadResearchExample  reads  the
file "pgrelfind.g" in the  res-examples  directory  which  defines
GAP functions such as PGRelFind, that were used in  CHHR01
to show that the group L3(5) has deficiency 0.
The deficiency of a finite presentation {X | R} of a finite group G is |R| - |X|, and the deficiency of the group G is the minimum of the deficiencies of all finite presentations of G.
Let us now invoke ACEReadResearchExample with no arguments:
gap> ACEReadResearchExample();
#I  The following are now defined:
#I  
#I  Functions:
#I    PGRelFind, ClassesGenPairs, TranslatePresentation,
#I    IsACEResExampleOK
#I  Variables:
#I    ACEResExample, ALLRELS, newrels, F, a, b, newF, x, y,
#I    L2_8, L2_16, L3_3s, U3_3s, M11, M12, L2_32,
#I    U3_4s, J1s, L3_5s, PSp4_4s, presentations
#I  
#I  Also:
#I  
#I  TCENUM = ACETCENUM  (Todd-Coxeter Enumerator is now ACE)
#I  
#I  For an example of their application, you might like to try:
#I  gap> ACEReadResearchExample("doL28.g" : optex := [1,2,4,5,8]);
#I  (the output is 65 lines followed by a 'gap> ' prompt)
#I  
#I  For information type: ?Using ACEReadResearchExample
gap> 
The output (Info-ed at InfoACELevel 1) states that a number of new
functions are defined. During a  GAP  session,  you  can  find  out
details of these functions by typing:
gap> ?Using ACEReadResearchExample
[Up] [Previous] [Next] [Index]
ACE manual