GAP 4.8.9 installation with standard packages -- copy to your CoCalc project to get it

1
<Appendix Label="Examples">
2
<Heading>Examples</Heading>
3

4
There are a large number of examples provided with the &ANUPQ; package. 
5
These may be executed or displayed via the function <C>PqExample</C>
6
(see&nbsp;<Ref Func="PqExample" Style="Text"/>). Each example resides in a file of the same name in the
7
directory <C>examples</C>. Most of the examples are translations to &GAP; of
8
examples provided for the <C>pq</C> standalone by Eamonn O'Brien; the
9
standalone examples are found in directories <C>standalone/examples</C>
10
(<M>p</M>-quotient and <M>p</M>-group generation examples) and <C>standalone/isom</C>
11
(standard presentation examples). The first line of each example
12
indicates its origin. All the examples seen in earlier chapters of this
13
manual are also available as examples, in a slightly modified form (the
14
example which one can run in order to see something very close to the
15
text example <Q>live</Q> is always indicated near -- usually immediately
16
after -- the text example). The format of the (<C>PqExample</C>) examples is
17
such that they can be read by the standard <C>Read</C> function of &GAP;, but
18
certain features and comments are interpreted by the function <C>PqExample</C>
19
to do somewhat more than <C>Read</C> does. In particular, any function without
20
a <C>-i</C>, <C>-ni</C> or <C>.g</C> suffix has both a non-interactive and interactive
21
form; in these cases, the default form is the non-interactive form, and
22
giving <C>PqStart</C> as second argument generates the interactive form.
23

24
<P/>
25

26
Running <C>PqExample</C> without an argument or with a non-existent example
27
<C>Info</C>s the available examples and some hints on usage:
28

29
<Example><![CDATA[
30
gap> PqExample();
31
#I                   PqExample Index (Table of Contents)
32
#I                   -----------------------------------
33
#I  This table of possible examples is displayed when calling `PqExample'
34
#I  with no arguments, or with the argument: "index" (meant in the  sense
35
#I  of ``list''), or with a non-existent example name.
36
#I  
37
#I  Examples that have a name ending in `-ni' are  non-interactive  only.
38
#I  Examples that have a  name  ending  in  `-i'  are  interactive  only.
39
#I  Examples with names ending in `.g' also have  only  one  form.  Other
40
#I  examples have both a non-interactive and an  interactive  form;  call
41
#I  `PqExample' with 2nd argument `PqStart' to get the  interactive  form
42
#I  of the example. The substring `PG' in an  example  name  indicates  a
43
#I  p-Group Generation example, `SP' indicates  a  Standard  Presentation
44
#I  example, `Rel' indicates it uses  the  `Relators'  option,  and  `Id'
45
#I  indicates it uses the `Identities' option.
46
#I  
47
#I  The following ANUPQ examples are available:
48
#I  
49
#I   p-Quotient examples:
50
#I    general:
51
#I     "Pq"                   "Pq-ni"                "PqEpimorphism"        
52
#I     "PqPCover"             "PqSupplementInnerAutomorphisms"
53
#I    2-groups:
54
#I     "2gp-Rel"              "2gp-Rel-i"            "2gp-a-Rel-i"
55
#I     "B2-4"                 "B2-4-Id"              "B2-8-i"
56
#I     "B4-4-i"               "B4-4-a-i"             "B5-4.g"
57
#I    3-groups:
58
#I     "3gp-Rel-i"            "3gp-a-Rel"            "3gp-a-Rel-i"
59
#I     "3gp-a-x-Rel-i"        "3gp-maxoccur-Rel-i"
60
#I    5-groups:
61
#I     "5gp-Rel-i"            "5gp-a-Rel-i"          "5gp-b-Rel-i"
62
#I     "5gp-c-Rel-i"          "5gp-metabelian-Rel-i" "5gp-maxoccur-Rel-i"
63
#I     "F2-5-i"               "B2-5-i"               "R2-5-i"
64
#I     "R2-5-x-i"             "B5-5-Engel3-Id"
65
#I    7-groups:
66
#I     "7gp-Rel-i"
67
#I    11-groups:
68
#I     "11gp-i"               "11gp-Rel-i"           "11gp-a-Rel-i"
69
#I     "11gp-3-Engel-Id"      "11gp-3-Engel-Id-i"
70
#I  
71
#I   p-Group Generation examples:
72
#I    general:
73
#I     "PqDescendants-1"      "PqDescendants-2"      "PqDescendants-3"
74
#I     "PqDescendants-1-i"
75
#I    2-groups:
76
#I     "2gp-PG-i"             "2gp-PG-2-i"           "2gp-PG-3-i"
77
#I     "2gp-PG-4-i"           "2gp-PG-e4-i"
78
#I     "PqDescendantsTreeCoclassOne-16-i"
79
#I    3-groups:
80
#I     "3gp-PG-i"             "3gp-PG-4-i"           "3gp-PG-x-i"
81
#I     "3gp-PG-x-1-i"         "PqDescendants-treetraverse-i"
82
#I     "PqDescendantsTreeCoclassOne-9-i"
83
#I    5-groups:
84
#I     "5gp-PG-i"             "Nott-PG-Rel-i"        "Nott-APG-Rel-i"
85
#I     "PqDescendantsTreeCoclassOne-25-i"
86
#I    7,11-groups:
87
#I     "7gp-PG-i"             "11gp-PG-i"
88
#I  
89
#I   Standard Presentation examples:
90
#I    general:
91
#I     "StandardPresentation" "StandardPresentation-i"
92
#I     "EpimorphismStandardPresentation"
93
#I     "EpimorphismStandardPresentation-i"           "IsIsomorphicPGroup-ni"
94
#I    2-groups:
95
#I     "2gp-SP-Rel-i"         "2gp-SP-1-Rel-i"       "2gp-SP-2-Rel-i"
96
#I     "2gp-SP-3-Rel-i"       "2gp-SP-4-Rel-i"       "2gp-SP-d-Rel-i"
97
#I     "gp-256-SP-Rel-i"      "B2-4-SP-i"            "G2-SP-Rel-i"
98
#I    3-groups:
99
#I     "3gp-SP-Rel-i"         "3gp-SP-1-Rel-i"       "3gp-SP-2-Rel-i"
100
#I     "3gp-SP-3-Rel-i"       "3gp-SP-4-Rel-i"       "G3-SP-Rel-i"
101
#I    5-groups:
102
#I     "5gp-SP-Rel-i"         "5gp-SP-a-Rel-i"       "5gp-SP-b-Rel-i"
103
#I     "5gp-SP-big-Rel-i"     "5gp-SP-d-Rel-i"       "G5-SP-Rel-i"
104
#I     "G5-SP-a-Rel-i"        "Nott-SP-Rel-i"
105
#I    7-groups:
106
#I     "7gp-SP-Rel-i"         "7gp-SP-a-Rel-i"       "7gp-SP-b-Rel-i"
107
#I    11-groups:
108
#I     "11gp-SP-a-i"          "11gp-SP-a-Rel-i"      "11gp-SP-a-Rel-1-i"
109
#I     "11gp-SP-b-i"          "11gp-SP-b-Rel-i"      "11gp-SP-c-Rel-i"
110
#I  
111
#I  Notes
112
#I  -----
113
#I  1. The example (first) argument of  `PqExample'  is  a  string;  each
114
#I     example above is in double quotes to remind you to include them.
115
#I  2. Some examples accept options. To find  out  whether  a  particular
116
#I     example accepts options, display it first (by including  `Display'
117
#I     as  last  argument)  which  will  also  indicate  how  `PqExample'
118
#I     interprets the options, e.g. `PqExample("11gp-SP-a-i", Display);'.
119
#I  3. Try `SetInfoLevel(InfoANUPQ, <n>);' for  some  <n>  in  [2  ..  4]
120
#I     before calling PqExample, to see what's going on behind the scenes.
121
#I  
122
]]></Example>
123

124
If on your terminal you are unable to scroll back, an alternative to
125
typing <C>PqExample();</C> to see the displayed examples is to use on-line
126
help, i.e.&nbsp; you may type:
127

128
<Log><![CDATA[
129
gap> ?anupq:examples
130
]]></Log>
131

132
which will display this appendix in a &GAP; session. If you are not
133
fussed about the order in which the examples are organised,
134
<C>AllPqExamples();</C> lists the available examples relatively compactly
135
(see&nbsp;<Ref Func="AllPqExamples" Style="Text"/>).
136
<P/>
137

138
In the remainder of this appendix we will discuss particular aspects
139
related to the <C>Relators</C> (see&nbsp;<Ref Label="option Relators" Style="Text"/>) and <C>Identities</C>
140
(see&nbsp;<Ref Label="option Identities" Style="Text"/>) options, and the construction of the Burnside
141
group <M>B(5, 4)</M>.
142

143

144
<Section Label="The Relators Option">
145
<Heading>The Relators Option</Heading>
146

147
The <C>Relators</C> option was included because computations involving words
148
containing commutators that are pre-expanded by &GAP; before being
149
passed to the <C>pq</C> program may run considerably more slowly, than the
150
same computations being run with &GAP; pre-expansions avoided. The
151
following examples demonstrate a case where the performance hit due to
152
pre-expansion of commutators by &GAP; is a factor of order 100 (in order
153
to see timing information from the <C>pq</C> program, we set the <C>InfoANUPQ</C>
154
level to 2).
155

156
<P/>
157

158
Firstly, we run the example that allows pre-expansion of commutators (the
159
function <C>PqLeftNormComm</C> is provided by the &ANUPQ; package;
160
see&nbsp;<Ref Func="PqLeftNormComm" Style="Text"/>). Note that since the two commutators of this
161
example are <E>very</E> long (taking more than an page to print), we have
162
edited the output at this point.
163

164
<Log><![CDATA[
165
gap> SetInfoLevel(InfoANUPQ, 2); #to see timing information
166
gap> PqExample("11gp-i");
167
#I  #Example: "11gp-i" . . . based on: examples/11gp
168
#I  F, a, b, c, R, procId are local to `PqExample'
169
gap> F := FreeGroup("a", "b", "c"); a := F.1; b := F.2; c := F.3;
170
<free group on the generators [ a, b, c ]>
171
a
172
b
173
c
174
gap> R := [PqLeftNormComm([b, a, a, b, c])^11, 
175
>          PqLeftNormComm([a, b, b, a, b, c])^11, (a * b)^11];;
176
gap> procId := PqStart(F/R : Prime := 11);
177
1
178
gap> PqPcPresentation(procId : ClassBound := 7, 
179
>                              OutputLevel := 1);
180
#I  Lower exponent-11 central series for [grp]
181
#I  Group: [grp] to lower exponent-11 central class 1 has order 11^3
182
#I  Group: [grp] to lower exponent-11 central class 2 has order 11^8
183
#I  Group: [grp] to lower exponent-11 central class 3 has order 11^19
184
#I  Group: [grp] to lower exponent-11 central class 4 has order 11^42
185
#I  Group: [grp] to lower exponent-11 central class 5 has order 11^98
186
#I  Group: [grp] to lower exponent-11 central class 6 has order 11^228
187
#I  Group: [grp] to lower exponent-11 central class 7 has order 11^563
188
#I  Computation of presentation took 27.04 seconds
189
gap> PqSavePcPresentation(procId, ANUPQData.outfile);
190
#I  Variables used in `PqExample' are saved in `ANUPQData.example.vars'.
191
]]></Log>
192

193
Now we do the same calculation using the <C>Relators</C> option. In this way,
194
the commutators are passed directly as strings to the <C>pq</C> program, so
195
that &GAP; does not <Q>see</Q> them and pre-expand them.
196

197
<Log><![CDATA[
198
gap> PqExample("11gp-Rel-i");
199
#I  #Example: "11gp-Rel-i" . . . based on: examples/11gp
200
#I  #(equivalent to "11gp-i" example but uses `Relators' option)
201
#I  F, rels, procId are local to `PqExample'
202
gap> F := FreeGroup("a", "b", "c");
203
<free group on the generators [ a, b, c ]>
204
gap> rels := ["[b, a, a, b, c]^11", "[a, b, b, a, b, c]^11", "(a * b)^11"];
205
[ "[b, a, a, b, c]^11", "[a, b, b, a, b, c]^11", "(a * b)^11" ]
206
gap> procId := PqStart(F : Prime := 11, Relators := rels);
207
2
208
gap> PqPcPresentation(procId : ClassBound := 7, 
209
>                              OutputLevel := 1);
210
#I  Relators parsed ok.
211
#I  Lower exponent-11 central series for [grp]
212
#I  Group: [grp] to lower exponent-11 central class 1 has order 11^3
213
#I  Group: [grp] to lower exponent-11 central class 2 has order 11^8
214
#I  Group: [grp] to lower exponent-11 central class 3 has order 11^19
215
#I  Group: [grp] to lower exponent-11 central class 4 has order 11^42
216
#I  Group: [grp] to lower exponent-11 central class 5 has order 11^98
217
#I  Group: [grp] to lower exponent-11 central class 6 has order 11^228
218
#I  Group: [grp] to lower exponent-11 central class 7 has order 11^563
219
#I  Computation of presentation took 0.27 seconds
220
gap> PqSavePcPresentation(procId, ANUPQData.outfile);
221
#I  Variables used in `PqExample' are saved in `ANUPQData.example.vars'.
222
]]></Log>
223
</Section>
224

225

226
<Section Label="The Identities Option and PqEvaluateIdentities Function">
227
<Heading>The Identities Option and PqEvaluateIdentities Function</Heading>
228

229
Please pay heed to the warnings given for the <C>Identities</C> option
230
(see&nbsp;<Ref Label="option Identities" Style="Text"/>); it is written mainly at the &GAP; level and
231
is not particularly optimised. The <C>Identities</C> option allows one to
232
compute <M>p</M>-quotients that satisfy an identity. A trivial example better
233
done using the <C>Exponent</C> option, but which nevertheless demonstrates the
234
usage of the <C>Identities</C> option, is as follows:
235

236
<Log><![CDATA[
237
gap> SetInfoLevel(InfoANUPQ, 1);
238
gap> PqExample("B2-4-Id");
239
#I  #Example: "B2-4-Id" . . . alternative way to generate B(2, 4)
240
#I  #Generates B(2, 4) by using the `Identities' option
241
#I  #... this is not as efficient as using `Exponent' but
242
#I  #demonstrates the usage of the `Identities' option.
243
#I  F, f, procId are local to `PqExample'
244
gap> F := FreeGroup("a", "b");
245
<free group on the generators [ a, b ]>
246
gap> # All words w in the pc generators of B(2, 4) satisfy f(w) = 1 
247
gap> f := w -> w^4;
248
function( w ) ... end
249
gap> Pq( F : Prime := 2, Identities := [ f ] );
250
#I  Class 1 with 2 generators.
251
#I  Class 2 with 5 generators.
252
#I  Class 3 with 7 generators.
253
#I  Class 4 with 10 generators.
254
#I  Class 5 with 12 generators.
255
#I  Class 5 with 12 generators.
256
<pc group of size 4096 with 12 generators>
257
#I  Variables used in `PqExample' are saved in `ANUPQData.example.vars'.
258
gap> time; 
259
1400
260
]]></Log>
261

262
Note that the <C>time</C> statement gives the time in milliseconds spent by
263
&GAP; in executing the <C>PqExample("B2-4-Id");</C> command (i.e.&nbsp;everything
264
up to the <C>Info</C>-ing of the variables used), but over 90% of that time
265
is spent in the final <C>Pq</C> statement. The time spent by the <C>pq</C> program,
266
which is negligible anyway (you can check this by running the example
267
while the <C>InfoANUPQ</C> level is set to 2), is not counted by <C>time</C>.
268

269
<P/>
270

271
Since the identity used in the above construction of <M>B(2, 4)</M> is just an
272
exponent law, the <Q>right</Q> way to compute it is via the <C>Exponent</C>
273
option (see&nbsp;<Ref Label="option Exponent" Style="Text"/>), which is implemented at the C level and
274
<E>is</E> highly optimised. Consequently, the <C>Exponent</C> option is
275
significantly faster, generally by several orders of magnitude:
276

277
<Log><![CDATA[
278
gap> SetInfoLevel(InfoANUPQ, 2); # to see time spent by the `pq' program
279
gap> PqExample("B2-4");
280
#I  #Example: "B2-4" . . . the ``right'' way to generate B(2, 4)
281
#I  #Generates B(2, 4) by using the `Exponent' option
282
#I  F, procId are local to `PqExample'
283
gap> F := FreeGroup("a", "b");
284
<free group on the generators [ a, b ]>
285
gap> Pq( F : Prime := 2, Exponent := 4 );
286
#I  Computation of presentation took 0.00 seconds
287
<pc group of size 4096 with 12 generators>
288
#I  Variables used in `PqExample' are saved in `ANUPQData.example.vars'.
289
gap> time; # time spent by GAP in executing `PqExample("B2-4");' 
290
50
291
]]></Log>
292

293
The following example uses the <C>Identities</C> option to compute a 3-Engel
294
group for the prime 11. As is the case for the example <C>"B2-4-Id"</C>, the
295
example has both a non-interactive and an interactive form; below, we
296
demonstrate the interactive form.
297

298
<Log><![CDATA[
299
gap> SetInfoLevel(InfoANUPQ, 1); # reset InfoANUPQ to default level
300
gap> PqExample("11gp-3-Engel-Id", PqStart);
301
#I  #Example: "11gp-3-Engel-Id" . . . 3-Engel group for prime 11
302
#I  #Non-trivial example of using the `Identities' option
303
#I  F, a, b, G, f, procId, Q are local to `PqExample'
304
gap> F := FreeGroup("a", "b"); a := F.1; b := F.2;
305
<free group on the generators [ a, b ]>
306
a
307
b
308
gap> G := F/[ a^11, b^11 ];
309
<fp group on the generators [ a, b ]>
310
gap> # All word pairs u, v in the pc generators of the 11-quotient Q of G 
311
gap> # must satisfy the Engel identity: [u, v, v, v] = 1.
312
gap> f := function(u, v) return PqLeftNormComm( [u, v, v, v] ); end;
313
function( u, v ) ... end
314
gap> procId := PqStart( G );
315
3
316
gap> Q := Pq( procId : Prime := 11, Identities := [ f ] );
317
#I  Class 1 with 2 generators.
318
#I  Class 2 with 3 generators.
319
#I  Class 3 with 5 generators.
320
#I  Class 3 with 5 generators.
321
<pc group of size 161051 with 5 generators>
322
gap> # We do a ``sample'' check that pairs of elements of Q do satisfy
323
gap> # the given identity:
324
gap> f( Random(Q), Random(Q) );
325
<identity> of ...
326
gap> f( Q.1, Q.2 );
327
<identity> of ...
328
#I  Variables used in `PqExample' are saved in `ANUPQData.example.vars'.
329
]]></Log>
330

331
The (interactive) call to <C>Pq</C> above is essentially equivalent to a call
332
to <C>PqPcPresentation</C> with the same arguments and options followed by a
333
call to <C>PqCurrentGroup</C>. Moreover, the call to <C>PqPcPresentation</C> (as
334
described in&nbsp;<Ref Func="PqPcPresentation" Style="Text"/>) is equivalent to a <Q>class 1</Q> call to
335
<C>PqPcPresentation</C> followed by the requisite number of calls to
336
<C>PqNextClass</C>, and with the <C>Identities</C> option set, both
337
<C>PqPcPresentation</C> and <C>PqNextClass</C> <Q>quietly</Q> perform the equivalent
338
of a <C>PqEvaluateIdentities</C> call. In the following example we break down
339
the <C>Pq</C> call into its low-level equivalents, and set and unset the
340
<C>Identities</C> option to show where <C>PqEvaluateIdentities</C> fits into this
341
scheme.
342

343
<Log><![CDATA[
344
gap> PqExample("11gp-3-Engel-Id-i");
345
#I  #Example: "11gp-3-Engel-Id-i" . . . 3-Engel grp for prime 11
346
#I  #Variation of "11gp-3-Engel-Id" broken down into its lower-level component
347
#I  #command parts.
348
#I  F, a, b, G, f, procId, Q are local to `PqExample'
349
gap> F := FreeGroup("a", "b"); a := F.1; b := F.2;
350
<free group on the generators [ a, b ]>
351
a
352
b
353
gap> G := F/[ a^11, b^11 ];
354
<fp group on the generators [ a, b ]>
355
gap> # All word pairs u, v in the pc generators of the 11-quotient Q of G 
356
gap> # must satisfy the Engel identity: [u, v, v, v] = 1.
357
gap> f := function(u, v) return PqLeftNormComm( [u, v, v, v] ); end;
358
function( u, v ) ... end
359
gap> procId := PqStart( G : Prime := 11 );
360
4
361
gap> PqPcPresentation( procId : ClassBound := 1);
362
gap> PqEvaluateIdentities( procId : Identities := [f] );
363
#I  Class 1 with 2 generators.
364
gap> for c in [2 .. 4] do
365
>      PqNextClass( procId : Identities := [] ); #reset `Identities' option
366
>      PqEvaluateIdentities( procId : Identities := [f] );
367
>    od;
368
#I  Class 2 with 3 generators.
369
#I  Class 3 with 5 generators.
370
#I  Class 3 with 5 generators.
371
gap> Q := PqCurrentGroup( procId );
372
<pc group of size 161051 with 5 generators>
373
gap> # We do a ``sample'' check that pairs of elements of Q do satisfy
374
gap> # the given identity:
375
gap> f( Random(Q), Random(Q) );
376
<identity> of ...
377
gap> f( Q.1, Q.2 );
378
<identity> of ...
379
#I  Variables used in `PqExample' are saved in `ANUPQData.example.vars'.
380
]]></Log>
381

382
</Section>
383

384

385
<Section Label="A Large Example">
386
<Heading>A Large Example</Heading>
387

388
<Index Key="B(5,4)"><M>B(5,4)</M></Index>
389
An example demonstrating how a large computation can be organised with the
390
&ANUPQ; package is the computation of the Burnside group <M>B(5, 4)</M>, the
391
largest group of exponent 4 generated by 5 elements. It has order
392
<M>2^{2728}</M> and lower exponent-<M>p</M> central class 13. The example
393
<C>"B5-4.g"</C> computes <M>B(5, 4)</M>; it is based on a <C>pq</C> standalone input
394
file written by M.&nbsp;F.&nbsp;Newman.
395
<P/>
396

397
To be able to do examples like this was part of the motivation to provide
398
access to the low-level functions of the standalone program from within
399
&GAP;.
400
<P/>
401

402
Please note that the construction uses the knowledge gained by Newman and
403
O'Brien in their initial construction of <M>B(5, 4)</M>, in particular,
404
insight into the commutator structure of the group and the knowledge of
405
the <M>p</M>-central class and the order of <M>B(5, 4)</M>. Therefore, the
406
construction cannot be used to prove that <M>B(5, 4)</M> has the order and
407
class mentioned above. It is merely a reconstruction of the group. More
408
information is contained in the header of the file <C>examples/B5-4.g</C>.
409

410
<Log><![CDATA[
411
procId := PqStart( FreeGroup(5) : Exponent := 4, Prime := 2 );
412
Pq( procId : ClassBound := 2 );
413
PqSupplyAutomorphisms( procId,
414
      [
415
        [ [ 1, 1, 0, 0, 0],      # first automorphism
416
          [ 0, 1, 0, 0, 0],
417
          [ 0, 0, 1, 0, 0],
418
          [ 0, 0, 0, 1, 0],
419
          [ 0, 0, 0, 0, 1] ],
420

421
        [ [ 0, 0, 0, 0, 1],      # second automorphism
422
          [ 1, 0, 0, 0, 0],
423
          [ 0, 1, 0, 0, 0],
424
          [ 0, 0, 1, 0, 0],
425
          [ 0, 0, 0, 1, 0] ]
426
                             ] );;
427

428
Relations :=
429
  [ [],          ## class 1
430
    [],          ## class 2
431
    [],          ## class 3
432
    [],          ## class 4
433
    [],          ## class 5
434
    [],          ## class 6
435
    ## class 7     
436
    [ [ "x2","x1","x1","x3","x4","x4","x4" ] ],
437
    ## class 8
438
    [ [ "x2","x1","x1","x3","x4","x5","x5","x5" ] ],
439
    ## class 9
440
    [ [ "x2","x1","x1","x3","x4","x4","x5","x5","x5" ],
441
      [ "x2","x1","x1","x2","x3","x4","x5","x5","x5" ],
442
      [ "x2","x1","x1","x3","x3","x4","x5","x5","x5" ] ],
443
    ## class 10
444
    [ [ "x2","x1","x1","x2","x3","x3","x4","x5","x5","x5" ],
445
      [ "x2","x1","x1","x3","x3","x4","x4","x5","x5","x5" ] ],
446
    ## class 11
447
    [ [ "x2","x1","x1","x2","x3","x3","x4","x4","x5","x5","x5" ],
448
      [ "x2","x1","x1","x2","x3","x1","x3","x4","x2","x4","x3" ] ],
449
    ## class 12
450
    [ [ "x2","x1","x1","x2","x3","x1","x3","x4","x2","x5","x5","x5" ],
451
      [ "x2","x1","x1","x3","x2","x4","x3","x5","x4","x5","x5","x5" ] ],
452
    ## class 13
453
    [ [ "x2","x1","x1","x2","x3","x1","x3","x4","x2","x4","x5","x5","x5" 
454
        ] ]
455
];
456

457
for class in [ 3 .. 13 ] do
458
    Print( "Computing class ", class, "\n" );
459
    PqSetupTablesForNextClass( procId );
460

461
    for w in [ class, class-1 .. 7 ] do
462

463
        PqAddTails( procId, w );   
464
        PqDisplayPcPresentation( procId );
465

466
        if Relations[ w ] <> [] then
467
            # recalculate automorphisms
468
            PqExtendAutomorphisms( procId );
469

470
            for r in Relations[ w ] do
471
                Print( "Collecting ", r, "\n" );
472
                PqCommutator( procId, r, 1 );
473
                PqEchelonise( procId );
474
                PqApplyAutomorphisms( procId, 15 ); #queue factor = 15
475
            od;
476

477
            PqEliminateRedundantGenerators( procId );
478
        fi;   
479
        PqComputeTails( procId, w );
480
    od;
481
    PqDisplayPcPresentation( procId );
482

483
    smallclass := Minimum( class, 6 );
484
    for w in [ smallclass, smallclass-1 .. 2 ] do
485
        PqTails( procId, w );
486
    od;
487
    # recalculate automorphisms
488
    PqExtendAutomorphisms( procId );
489
    PqCollect( procId, "x5^4" );
490
    PqEchelonise( procId );
491
    PqApplyAutomorphisms( procId, 15 ); #queue factor = 15
492
    PqEliminateRedundantGenerators( procId );
493
    PqDisplayPcPresentation( procId );
494
od;
495
]]></Log>
496

497
</Section>
498

499

500
<Section Label="Developing descendants trees">
501
<Heading>Developing descendants trees</Heading>
502

503
In the following example we will explore the 3-groups of rank 2 and
504
3-coclass 1 up to 3-class 5. This will be done using the <M>p</M>-group
505
generation machinery of the package. We start with the elementary abelian
506
3-group of rank 2. From within &GAP;, run the example
507
<C>"PqDescendants-treetraverse-i"</C> via <C>PqExample</C> (see&nbsp;<Ref Func="PqExample" Style="Text"/>).
508

509
<Example><![CDATA[
510
gap> G := ElementaryAbelianGroup( 9 );
511
<pc group of size 9 with 2 generators>
512
gap> procId := PqStart( G );
513
5
514
gap> #
515
gap> #  Below, we use the option StepSize in order to construct descendants
516
gap> #  of coclass 1. This is equivalent to setting the StepSize to 1 in
517
gap> #  each descendant calculation.
518
gap> #
519
gap> #  The elementary abelian group of order 9 has 3 descendants of
520
gap> #  3-class 2 and 3-coclass 1, as the result of the next command
521
gap> #  shows. 
522
gap> #
523
gap> PqDescendants( procId : StepSize := 1 );
524
[ <pc group of size 27 with 3 generators>, 
525
  <pc group of size 27 with 3 generators>, 
526
  <pc group of size 27 with 3 generators> ]
527
gap> #
528
gap> #  Now we will compute the descendants of coclass 1 for each of the
529
gap> #  groups above. Then we will compute the descendants  of coclass 1
530
gap> #  of each descendant and so  on.  Note  that the  pq program keeps
531
gap> #  one file for each class at a time.  For example, the descendants
532
gap> #  calculation for  the  second  group  of class  2  overwrites the
533
gap> #  descendant file  obtained  from  the  first  group  of  class 2.
534
gap> #  Hence,  we have to traverse the descendants tree  in depth first
535
gap> #  order.
536
gap> #
537
gap> PqPGSetDescendantToPcp( procId, 2, 1 );
538
gap> PqPGExtendAutomorphisms( procId );
539
gap> PqPGConstructDescendants( procId : StepSize := 1 );
540
2
541
gap> PqPGSetDescendantToPcp( procId, 3, 1 );
542
gap> PqPGExtendAutomorphisms( procId );
543
gap> PqPGConstructDescendants( procId : StepSize := 1 );
544
2
545
gap> PqPGSetDescendantToPcp( procId, 4, 1 );
546
gap> PqPGExtendAutomorphisms( procId );
547
gap> PqPGConstructDescendants( procId : StepSize := 1 );
548
2
549
gap> #
550
gap> #  At this point we stop traversing the ``left most'' branch of the
551
gap> #  descendants tree and move upwards.
552
gap> #
553
gap> PqPGSetDescendantToPcp( procId, 4, 2 );
554
gap> PqPGExtendAutomorphisms( procId );
555
gap> PqPGConstructDescendants( procId : StepSize := 1 );
556
#I  group restored from file is incapable
557
0
558
gap> PqPGSetDescendantToPcp( procId, 3, 2 );
559
gap> PqPGExtendAutomorphisms( procId );
560
gap> PqPGConstructDescendants( procId : StepSize := 1 );
561
#I  group restored from file is incapable
562
0
563
gap> #  
564
gap> #  The computations above indicate that the descendants subtree under
565
gap> #  the first descendant of the elementary abelian group of order 9
566
gap> #  will have only one path of infinite length.
567
gap> #
568
gap> PqPGSetDescendantToPcp( procId, 2, 2 );
569
gap> PqPGExtendAutomorphisms( procId );
570
gap> PqPGConstructDescendants( procId : StepSize := 1 );
571
4
572
gap> #
573
gap> #  We get four descendants here, three of which will turn out to be
574
gap> #  incapable, i.e., they have no descendants and are terminal nodes
575
gap> #  in the descendants tree.
576
gap> #
577
gap> PqPGSetDescendantToPcp( procId, 2, 3 );
578
gap> PqPGExtendAutomorphisms( procId );
579
gap> PqPGConstructDescendants( procId : StepSize := 1 );
580
#I  group restored from file is incapable
581
0
582
gap> #
583
gap> #  The third descendant of class three is incapable.  Let us return
584
gap> #  to the second descendant of class 2.
585
gap> #
586
gap> PqPGSetDescendantToPcp( procId, 2, 2 );
587
gap> PqPGExtendAutomorphisms( procId );
588
gap> PqPGConstructDescendants( procId : StepSize := 1 );
589
4
590
gap> PqPGSetDescendantToPcp( procId, 3, 1 );
591
gap> PqPGExtendAutomorphisms( procId );
592
gap> PqPGConstructDescendants( procId : StepSize := 1 );
593
#I  group restored from file is incapable
594
0
595
gap> PqPGSetDescendantToPcp( procId, 3, 2 );
596
gap> PqPGExtendAutomorphisms( procId );
597
gap> PqPGConstructDescendants( procId : StepSize := 1 );
598
#I  group restored from file is incapable
599
0
600
gap> #
601
gap> #  We skip the third descendant for the moment ... 
602
gap> #
603
gap> PqPGSetDescendantToPcp( procId, 3, 4 );
604
gap> PqPGExtendAutomorphisms( procId );
605
gap> PqPGConstructDescendants( procId : StepSize := 1 );
606
#I  group restored from file is incapable
607
0
608
gap> #
609
gap> #  ... and look at it now.
610
gap> #
611
gap> PqPGSetDescendantToPcp( procId, 3, 3 );
612
gap> PqPGExtendAutomorphisms( procId );
613
gap> PqPGConstructDescendants( procId : StepSize := 1 );
614
6
615
gap> #
616
gap> #  In this branch of the descendant tree we get 6 descendants of class
617
gap> #  three.  Of those 5 will turn out to be incapable and one will have
618
gap> #  7 descendants.
619
gap> #
620
gap> PqPGSetDescendantToPcp( procId, 4, 1 );
621
gap> PqPGExtendAutomorphisms( procId );
622
gap> PqPGConstructDescendants( procId : StepSize := 1 );
623
#I  group restored from file is incapable
624
0
625
gap> PqPGSetDescendantToPcp( procId, 4, 2 );
626
gap> PqPGExtendAutomorphisms( procId );
627
gap> PqPGConstructDescendants( procId : StepSize := 1 );
628
7
629
gap> PqPGSetDescendantToPcp( procId, 4, 3 );
630
gap> PqPGExtendAutomorphisms( procId );
631
gap> PqPGConstructDescendants( procId : StepSize := 1 );
632
#I  group restored from file is incapable
633
0
634
]]></Example>
635

636
To automate the above procedure to some extent we provide:
637

638
<ManSection>
639
<Func Name="PqDescendantsTreeCoclassOne" Arg="i"/>
640
<Func Name="PqDescendantsTreeCoclassOne" Arg="" Label="for default process"/>
641

642
<Description>
643
for the <A>i</A>th or default interactive &ANUPQ; process, generate a
644
descendant tree for the group of the process (which must be a pc
645
<M>p</M>-group) consisting of descendants of <M>p</M>-coclass 1 and extending to
646
the class determined by the option <C>TreeDepth</C> (or 6 if the option is
647
omitted). In an &XGAP; session, a graphical representation of the
648
descendants tree appears in a separate window. Subsequent calls to
649
<C>PqDescendantsTreeCoclassOne</C> for the same process may be used to extend
650
the descendant tree from the last descendant computed that itself has
651
more than one descendant. <C>PqDescendantsTreeCoclassOne</C> also accepts the
652
options <C>CapableDescendants</C> (or <C>AllDescendants</C>) and any options
653
accepted by the interactive <C>PqDescendants</C> function
654
(see&nbsp;<Ref Func="PqDescendants" Label="interactive" Style="Text"/>).
655
<P/>
656

657
<E>Notes</E>
658
<Enum>
659
    <Item>
660
    <C>PqDescendantsTreeCoclassOne</C> first calls <C>PqDescendants</C>. If
661
    <C>PqDescendants</C> has already been called for the process, the previous
662
    value computed is used and a warning is <C>Info</C>-ed at <C>InfoANUPQ</C> level 1.
663
    </Item>
664

665
    <Item>
666
    As each descendant is processed its unique label defined by the <C>pq</C>
667
    program and number of descendants is <C>Info</C>-ed at <C>InfoANUPQ</C> level 1.
668
    </Item>
669

670
    <Item>
671
    <C>PqDescendantsTreeCoclassOne</C> is an <Q>experimental</Q> function that is
672
    included to demonstrate the sort of things that are possible with the
673
    <M>p</M>-group generation machinery.
674
    </Item>
675
</Enum>
676

677
Ignoring the extra functionality provided in an &XGAP; session,
678
<C>PqDescendantsTreeCoclassOne</C>, with one argument that is the index of an
679
interactive &ANUPQ; process, is approximately equivalent to:
680

681
<Listing><![CDATA[
682
PqDescendantsTreeCoclassOne := function( procId )
683
    local des, i;
684

685
    des := PqDescendants( procId : StepSize := 1 );
686
    RecurseDescendants( procId, 2, Length(des) );
687
end;
688
]]></Listing>
689

690
where <C>RecurseDescendants</C> is (approximately) defined as follows:
691

692
<Listing><![CDATA[
693
RecurseDescendants := function( procId, class, n )
694
    local i, nr;
695

696
    if class > ValueOption("TreeDepth") then return; fi;
697

698
    for i in [1..n] do
699
        PqPGSetDescendantToPcp( procId, class, i );
700
        PqPGExtendAutomorphisms( procId );
701
        nr := PqPGConstructDescendants( procId : StepSize := 1 );
702
        Print( "Number of descendants of group ", i,
703
               " at class ", class, ": ", nr, "\n" );
704
        RecurseDescendants( procId, class+1, nr );
705
    od;
706
    return;
707
end;
708
]]></Listing>
709

710
The following examples (executed via <C>PqExample</C>; see&nbsp;<Ref Func="PqExample" Style="Text"/>),
711
demonstrate the use of <C>PqDescendantsTreeCoclassOne</C>:
712

713
<List>
714
<Mark><C>"PqDescendantsTreeCoclassOne-9-i"</C></Mark>
715
<Item>
716
approximately does example <C>"PqDescendants-treetraverse-i"</C> again using
717
<C>PqDescendantsTreeCoclassOne</C>;
718
</Item>
719
<Mark><C>"PqDescendantsTreeCoclassOne-16-i"</C></Mark>
720
<Item>
721
uses the option <C>CapableDescendants</C>; and
722
</Item>
723
<Mark><C>"PqDescendantsTreeCoclassOne-25-i"</C></Mark>
724
<Item>
725
calculates all descendants by omitting the <C>CapableDescendants</C> option.
726
</Item>
727
</List>
728

729
The numbers <C>9</C>, <C>16</C> and <C>25</C> respectively, indicate the order of the
730
elementary abelian group to which <C>PqDescendantsTreeCoclassOne</C> is
731
applied for these examples.
732
</Description>
733
</ManSection>
734

735
</Section>
736
</Appendix>
737

738