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

1
  
2
  7 Technicalities of the AtlasRep Package
3
  
4
  This  chapter  describes  those  parts  of the GAP interface to the ATLAS of
5
  Group   Representations   that   do   not   belong  to  the  user  interface
6
  (cf. Chapter 3).
7
  
8
  Besides   global   variables   used   for   administrational  purposes  (see
9
  Section 7.1)  and  several  sanity  checks  (see  Section 7.8),  they can be
10
  regarded  as  the interface between the data actually contained in the files
11
  and  the corresponding GAP objects (see Section 7.2, 7.3, 7.4, and 7.5), and
12
  the  interface between the remote and the local version of the database (see
13
  Section 7.6  and 7.7).  The  former interface contains functions to read and
14
  write  files  in MeatAxe format, which may be interesting for users familiar
15
  with  MeatAxe standalones (see for example [Rin]). Other low level functions
16
  may be undocumented in the sense that they are not described in this manual.
17
  Users  interested  in  them may look at the actual implementation in the gap
18
  directory  of  the  package,  but it may happen that this will be changed in
19
  future versions of the package.
20
  
21
  
22
  7.1 Global Variables Used by the AtlasRep Package
23
  
24
  For debugging purposes, the functions from the GAP interface to the ATLAS of
25
  Group  Representations  print information depending on the info level of the
26
  info  classes  InfoAtlasRep  (7.1-1),  InfoCMeatAxe  (7.1-2),  and  InfoBBox
27
  (7.1-3) (cf. 'Reference: Info Functions').
28
  
29
  The  info  level  of  an  info  class  can  be  changed  using  SetInfoLevel
30
  (Reference:  SetInfoLevel).  For  example,  the  info  level of InfoAtlasRep
31
  (7.1-1)  can  be  set  to  the  nonnegative  integer  n  using SetInfoLevel(
32
  InfoAtlasRep, n ).
33
  
34
  Information  about  files being read can be obtained by setting the value of
35
  the global variable InfoRead1 to Print (Reference: Print).
36
  
37
  7.1-1 InfoAtlasRep
38
  
39
  InfoAtlasRep info class
40
  
41
  If  the info level of InfoAtlasRep is at least 1 then information about fail
42
  results  of  functions in the AtlasRep package is printed. If the info level
43
  is  at least 2 then information about calls to external programs is printed.
44
  The default level is 0, no information is printed on this level.
45
  
46
  7.1-2 InfoCMeatAxe
47
  
48
  InfoCMeatAxe info class
49
  
50
  If  the info level of InfoCMeatAxe is at least 1 then information about fail
51
  results  of  C-MeatAxe  functions  is printed. The default level is zero, no
52
  information is printed on this level.
53
  
54
  7.1-3 InfoBBox
55
  
56
  InfoBBox info class
57
  
58
  If  the  info  level  of  InfoBBox is at least 1 then information about fail
59
  results  of  functions  dealing with black box programs (see Section 6.2) is
60
  printed. The default level is 0, no information is printed on this level.
61
  
62
  7.1-4 CMeatAxe.FastRead
63
  
64
  CMeatAxe.FastRead global variable
65
  
66
  If  this  component  is  bound  and  has the value true then ScanMeatAxeFile
67
  (7.3-1) reads text files via StringFile (GAPDoc: StringFile). Otherwise each
68
  file  containing  a  matrix  over  a  finite  field is read line by line via
69
  ReadLine  (Reference:  ReadLine),  and the GAP matrix is constructed line by
70
  line,  in  a  compressed  representation  (see 'Reference:  Row Vectors over
71
  Finite Fields' and 'Reference: Matrices over Finite Fields'), which makes it
72
  possible  to  read  large  matrices  in  a  reasonable  amount of space. The
73
  StringFile   (GAPDoc:   StringFile)   approach  is  faster  but  needs  more
74
  intermediate  space  when  text files containing matrices over finite fields
75
  are read.
76
  
77
  7.1-5 AGR
78
  
79
  AGR global variable
80
  
81
  is  a  record  whose  components are functions and data that are used by the
82
  higher level interface functions.
83
  
84
  7.1-6 AtlasOfGroupRepresentationsInfo
85
  
86
  AtlasOfGroupRepresentationsInfo global variable
87
  
88
  This  is  a  record  that is defined in the file gap/types.g of the package,
89
  with the following components.
90
  
91
  Components corresponding to user parameters (see Section 4.3) are
92
  
93
  remote
94
        a boolean that controls what files are available; if the value is true
95
        then  GAP is allowed to try remotely accessing any ATLAS file from the
96
        servers  (see  below) and thus all files listed in the global table of
97
        contents are available, if the value is false then GAP may access only
98
        those  files  that are stored in the database directories of the local
99
        GAP installation (see Section 4.3-1),
100
  
101
  servers
102
        a  list  of  pairs [ server, path ], where server is a string denoting
103
        the  http  address of a server where files can be fetched that are not
104
        stored in the local database, and path is a string describing the path
105
        where the data directories on the server reside,
106
  
107
  wget
108
        controls  whether  the  GAP package IO [Neu14] or the external program
109
        wget is used to fetch data files, see 4.3-3,
110
  
111
  compress
112
        a  boolean  that controls whether MeatAxe format text files are stored
113
        in  compressed  form;  if  the  value  is  true  then  these files are
114
        compressed  with  gzip after they have been fetched from a server, see
115
        Section 4.3-4,
116
  
117
  displayFunction
118
        the function that is used by DisplayAtlasInfo (3.5-1) for printing the
119
        formatted data, see Section 4.3-5,
120
  
121
  accessFunctions
122
        a  list  of records, each describing how to access the data files, see
123
        Sections 4.3-6 and 7.2, and
124
  
125
  markprivate
126
        a  string  used  in DisplayAtlasInfo (3.5-1) to mark private data, see
127
        Section  5.2.
128
  
129
  System components (which are computed automatically) are
130
  
131
  GAPnames
132
        a  list of pairs, each containing the GAP name and the ATLAS-file name
133
        of a group, see Section 3.2,
134
  
135
  groupnames
136
        a  list  of triples, each containing at the first position the name of
137
        the  directory  on each server that contains data about the group G in
138
        question,  at  the  second  position  the name of the (usually simple)
139
        group  for which a subdirectory exists that contains the data about G,
140
        and  at  the  third  position  the  ATLAS-file  name  used  for G, see
141
        Section 7.6,
142
  
143
  private
144
        a  list  of pairs of strings used for administrating private data (see
145
        Chapter 5);        the        value        is        changed        by
146
        AtlasOfGroupRepresentationsNotifyPrivateDirectory      (5.1-1)     and
147
        AtlasOfGroupRepresentationsForgetPrivateDirectory (5.1-2),
148
  
149
  characterinfo, permrepinfo, ringinfo
150
        additional   information   about   representations,   concerning   the
151
        characters    afforded,   the   point   stabilizers   of   permutation
152
        representations, and the ring of definition of matrix representations;
153
        this information is used by DisplayAtlasInfo (3.5-1),
154
  
155
  TableOfContents
156
        a  record  with  at  most the components local, remote, types, and the
157
        names  of private data directories. The values of the components local
158
        and remote can be computed automatically by ReloadAtlasTableOfContents
159
        (4.2-1),    the   value   of   the   component   types   is   set   in
160
        AGR.DeclareDataType  (7.5-1),  and  the  values  of the components for
161
        local        data        directories        are       created       by
162
        AtlasOfGroupRepresentationsNotifyPrivateDirectory (5.1-1).
163
  
164
  
165
  7.2 How to Customize the Access to Data files
166
  
167
  We discuss the three steps listed in Section 4.3-6.
168
  
169
  For  creating  an overview of the locally available data, the first of these
170
  steps  must  be  available  independent  of  actually  accessing the file in
171
  question.  For updating the local copy of the server data, the second of the
172
  above  steps  must be available independent of the third one. Therefore, the
173
  package  provides  the possibility to extend the default behaviour by adding
174
  new      records      to      the      accessFunctions      component     of
175
  AtlasOfGroupRepresentationsInfo (7.1-6). Its components are as follows.
176
  
177
  
178
  location( filename, groupname, dirname,
179
               type )
180
  
181
        Let  filename  be  the default filename (without path) of the required
182
        file,  or a list of such filenames. Let groupname be the ATLAS name of
183
        the  group  to  which  the  data in these files belong, dirname be the
184
        default  directory  name  (one of "datagens", "dataword", or the dirid
185
        value         of         a        private        directory,        see
186
        AtlasOfGroupRepresentationsNotifyPrivateDirectory  (5.1-1)),  and type
187
        be the data type (see AGR.DeclareDataType (7.5-1)). This function must
188
        return  either the absolute path(s) where the mechanism implemented by
189
        the  current record expects the local version of the given file(s), or
190
        fail  if this function does not feel responsible for these file(s). In
191
        the  latter  case, the location function in another record will know a
192
        path.
193
  
194
        The  file(s) is/are regarded as not locally available if all installed
195
        location  functions  return either fail or paths of nonexisting files,
196
        in the sense of IsExistingFile (Reference: IsExistingFile).
197
  
198
  
199
  fetch( filepath, filename, groupname,
200
            dirname, type )
201
  
202
        This  function  is  called when a file is not locally available and if
203
        the  location  function in the current record has returned a path or a
204
        list  of paths. The arguments dirname and type must be the same as for
205
        the  location function, and filepath and filename must be strings (not
206
        lists of strings).
207
  
208
        The  return  value  must be true if the function succeeded with making
209
        the  file  locally available (including postprocessing if applicable),
210
        and false otherwise.
211
  
212
  contents( filepath, type )
213
        This  function  is  called  when  the location function in the current
214
        record  has  returned  the  path(s)  filepath, and if either these are
215
        paths  of  existing  files or the fetch function in the current record
216
        has  been  called  for these paths, and the return value was true. The
217
        argument  type  must  be  the  same  as for the location and the fetch
218
        functions.
219
  
220
        The  return  value  must  be the contents of the file(s), in the sense
221
        that  the  GAP  matrix, matrix list, permutation, permutation list, or
222
        program  described by the file(s) is returned. This means that besides
223
        reading  the  file(s)  via  the appropriate function, interpreting the
224
        contents may be necessary.
225
  
226
  description
227
        This  must  be  a short string that describes for which kinds of files
228
        the  functions  in the current record are intended, which file formats
229
        are      supported      etc.      The     value     is     used     by
230
        AtlasOfGroupRepresentationsUserParameters (4.3-8).
231
  
232
  active
233
        The  current  accessFunctions  record  is  ignored by AGR.FileContents
234
        (7.6-2) if the value is not true.
235
  
236
  In AGR.FileContents (7.6-2), the records in the accessFunctions component of
237
  AtlasOfGroupRepresentationsInfo (7.1-6) are considered in reversed order.
238
  
239
  By default, the accessFunctions list contains three records. Only for one of
240
  them,  the active component has the value true. One of the other two records
241
  can  be  used  to  change  the  access to permutation representations and to
242
  matrix representations over finite fields such that MeatAxe binary files are
243
  transferred  and read instead of MeatAxe text files. The fourth record makes
244
  sense  only  if a local server is accessible, i. e., if the server files can
245
  be read directly, without being transferred into the data directories of the
246
  package.
247
  
248
  
249
  7.3 Reading and Writing MeatAxe Format Files
250
  
251
  7.3-1 ScanMeatAxeFile
252
  
253
  ScanMeatAxeFile( filename[, q][, "string"] )  function
254
  Returns:  the  matrix  or list of permutations stored in the file or encoded
255
            by the string.
256
  
257
  Let  filename be the name of a GAP readable file (see 'Reference: Filename')
258
  that contains a matrix or a permutation or a list of permutations in MeatAxe
259
  text  format  (see  the  section  about  the  program  zcv  in the C-MeatAxe
260
  documentation [Rin]),  and  let  q be a prime power. ScanMeatAxeFile returns
261
  the corresponding GAP matrix or list of permutations, respectively.
262
  
263
  If the file contains a matrix then the way how it is read by ScanMeatAxeFile
264
  depends on the value of the global variable CMeatAxe.FastRead (7.1-4).
265
  
266
  If  the  parameter q is given then the result matrix is represented over the
267
  field  with  q  elements,  the default for q is the field size stored in the
268
  file.
269
  
270
  If  the file contains a list of permutations then it is read with StringFile
271
  (GAPDoc: StringFile); the parameter q, if given, is ignored in this case.
272
  
273
  If  the  string  "string"  is  entered  as the third argument then the first
274
  argument  must  be  a  string  as obtained by reading a file in MeatAxe text
275
  format as a text stream (see InputTextFile (Reference: InputTextFile)). Also
276
  in  this  case, ScanMeatAxeFile returns the corresponding GAP matrix or list
277
  of permutations, respectively.
278
  
279
  7.3-2 MeatAxeString
280
  
281
  MeatAxeString( mat, q )  operation
282
  MeatAxeString( perms, degree )  operation
283
  MeatAxeString( perm, q, dims )  operation
284
  Returns:  a  string  encoding  the  GAP  objects  given  as input in MeatAxe
285
            format.
286
  
287
  In  the  first  form, for a matrix mat whose entries lie in the finite field
288
  with q elements, MeatAxeString returns a string that encodes mat as a matrix
289
  over GF(q), in MeatAxe text format.
290
  
291
  In the second form, for a nonempty list perms of permutations that move only
292
  points  up  to  the  positive integer degree, MeatAxeString returns a string
293
  that  encodes  perms  as  permutations  of  degree degree, in C-MeatAxe text
294
  format (see [Rin]).
295
  
296
  In the third form, for a permutation perm with largest moved point n, say, a
297
  prime  power  q,  and  a  list  dims  of  length two containing two positive
298
  integers  larger  than  or  equal  to n, MeatAxeString returns a string that
299
  encodes  perm as a matrix over GF(q), of dimensions dims, whose first n rows
300
  and  columns  describe the permutation matrix corresponding to perm, and the
301
  remaining rows and columns are zero.
302
  
303
  When  strings  are  printed  to  files using PrintTo (Reference: PrintTo) or
304
  AppendTo  (Reference: AppendTo) then line breaks are inserted whenever lines
305
  exceed  the  number  of  characters  given  by  the second entry of the list
306
  returned  by  SizeScreen (Reference: SizeScreen), see 'Reference: Operations
307
  for  Output  Streams'.  This  behaviour  is  not desirable for creating data
308
  files. So the recommended functions for printing the result of MeatAxeString
309
  to  a  file  are  FileString  (GAPDoc:  FileString) and WriteAll (Reference:
310
  WriteAll).
311
  
312
    Example  
313
    gap> mat:= [ [ 1, -1 ], [ 0, 1 ] ] * Z(3)^0;;
314
    gap> str:= MeatAxeString( mat, 3 );
315
    "1 3 2 2\n12\n01\n"
316
    gap> mat = ScanMeatAxeFile( str, "string" );
317
    true
318
    gap> str:= MeatAxeString( mat, 9 );
319
    "1 9 2 2\n12\n01\n"
320
    gap> mat = ScanMeatAxeFile( str, "string" );
321
    true
322
    gap> perms:= [ (1,2,3)(5,6) ];;
323
    gap> str:= MeatAxeString( perms, 6 );
324
    "12 1 6 1\n2\n3\n1\n4\n6\n5\n"
325
    gap> perms = ScanMeatAxeFile( str, "string" );
326
    true
327
    gap> str:= MeatAxeString( perms, 8 );
328
    "12 1 8 1\n2\n3\n1\n4\n6\n5\n7\n8\n"
329
    gap> perms = ScanMeatAxeFile( str, "string" );
330
    true
331
  
332
  
333
  Note  that  the  output of MeatAxeString in the case of permutation matrices
334
  depends on the user preference WriteMeatAxeFilesOfMode2.
335
  
336
    Example  
337
    gap> perm:= (1,2,4);;
338
    gap> str:= MeatAxeString( perm, 3, [ 5, 6 ] );
339
    "2 3 5 6\n2\n4\n3\n1\n5\n"
340
    gap> mat:= ScanMeatAxeFile( str, "string" );;  Print( mat, "\n" );
341
    [ [ 0*Z(3), Z(3)^0, 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3) ], 
342
      [ 0*Z(3), 0*Z(3), 0*Z(3), Z(3)^0, 0*Z(3), 0*Z(3) ], 
343
      [ 0*Z(3), 0*Z(3), Z(3)^0, 0*Z(3), 0*Z(3), 0*Z(3) ], 
344
      [ Z(3)^0, 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3) ], 
345
      [ 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3), Z(3)^0, 0*Z(3) ] ]
346
    gap> pref:= UserPreference( "AtlasRep", "WriteMeatAxeFilesOfMode2" );;
347
    gap> SetUserPreference( "AtlasRep", "WriteMeatAxeFilesOfMode2", true );
348
    gap> MeatAxeString( mat, 3 ) = str;
349
    true
350
    gap> SetUserPreference( "AtlasRep", "WriteMeatAxeFilesOfMode2", false );
351
    gap> MeatAxeString( mat, 3 );
352
    "1 3 5 6\n010000\n000100\n001000\n100000\n000010\n"
353
    gap> SetUserPreference( "AtlasRep", "WriteMeatAxeFilesOfMode2", pref );
354
  
355
  
356
  7.3-3 FFList
357
  
358
  FFList( F )  function
359
  Returns:  a list of elements in the given finite field.
360
  
361
  FFLists global variable
362
  
363
  FFList  is a utility program for the conversion of vectors and matrices from
364
  MeatAxe  format  to GAP format and vice versa. It is used by ScanMeatAxeFile
365
  (7.3-1) and MeatAxeString (7.3-2).
366
  
367
  For  a  finite  field  F,  FFList returns a list l giving the correspondence
368
  between the MeatAxe numbering and the GAP numbering of the elements in F.
369
  
370
  The  element  of  F  corresponding  to MeatAxe number n is l[ n+1 ], and the
371
  MeatAxe number of the field element z is Position( l, z ) - 1.
372
  
373
  The global variable FFLists is used to store the information about F once it
374
  has been computed.
375
  
376
    Example  
377
    gap> FFList( GF(4) );
378
    [ 0*Z(2), Z(2)^0, Z(2^2), Z(2^2)^2 ]
379
    gap> IsBound( FFLists[4] );
380
    true
381
  
382
  
383
  7.3-4 CMtxBinaryFFMatOrPerm
384
  
385
  CMtxBinaryFFMatOrPerm( elm, def, outfile[, base] )  function
386
  
387
  Let  the  pair  (elm,  def) be either of the form (M, q) where M is a matrix
388
  over  a  finite  field  F, say, with q ≤ 256 elements, or of the form (π, n)
389
  where  π is a permutation with largest moved point at most n. Let outfile be
390
  a  string.  CMtxBinaryFFMatOrPerm  writes  the C-MeatAxe binary format of M,
391
  viewed as a matrix over F, or of π, viewed as a permutation on the points up
392
  to n, to the file with name outfile.
393
  
394
  In  the  case  of  a  permutation  π,  the optional argument base prescribes
395
  whether  the  binary  file  contains  the  points from 0 to deg- 1 (base= 0,
396
  supported  by  version 2.4  of  the  C-MeatAxe)  or the points from 1 to deg
397
  (base=  1,  supported  by  older versions of the C-MeatAxe). The default for
398
  base  is given by the value of the user preference BaseOfMeatAxePermutation,
399
  see Section 4.3-11.
400
  
401
  (The binary format is described in the C-MeatAxe manual [Rin].)
402
  
403
    Example  
404
    gap> tmpdir:= DirectoryTemporary();;
405
    gap> mat:= Filename( tmpdir, "mat" );;
406
    gap> q:= 4;;
407
    gap> mats:= GeneratorsOfGroup( GL(10,q) );;
408
    gap> CMtxBinaryFFMatOrPerm( mats[1], q, Concatenation( mat, "1" ) );
409
    gap> CMtxBinaryFFMatOrPerm( mats[2], q, Concatenation( mat, "2" ) );
410
    gap> prm:= Filename( tmpdir, "prm" );;
411
    gap> n:= 200;;
412
    gap> perms:= GeneratorsOfGroup( SymmetricGroup( n ) );;
413
    gap> CMtxBinaryFFMatOrPerm( perms[1], n, Concatenation( prm, "1" ) );
414
    gap> CMtxBinaryFFMatOrPerm( perms[2], n, Concatenation( prm, "2" ) );
415
    gap> CMtxBinaryFFMatOrPerm( perms[1], n, Concatenation( prm, "1a" ), 0 );
416
    gap> CMtxBinaryFFMatOrPerm( perms[2], n, Concatenation( prm, "2b" ), 1 );
417
  
418
  
419
  7.3-5 FFMatOrPermCMtxBinary
420
  
421
  FFMatOrPermCMtxBinary( fname )  function
422
  Returns:  the matrix or permutation stored in the file.
423
  
424
  Let fname be the name of a file that contains the C-MeatAxe binary format of
425
  a  matrix over a finite field or of a permutation, as is described in [Rin].
426
  FFMatOrPermCMtxBinary returns the corresponding GAP matrix or permutation.
427
  
428
    Example  
429
    gap> FFMatOrPermCMtxBinary( Concatenation( mat, "1" ) ) = mats[1];
430
    true
431
    gap> FFMatOrPermCMtxBinary( Concatenation( mat, "2" ) ) = mats[2];
432
    true
433
    gap> FFMatOrPermCMtxBinary( Concatenation( prm, "1" ) ) = perms[1];
434
    true
435
    gap> FFMatOrPermCMtxBinary( Concatenation( prm, "2" ) ) = perms[2];
436
    true
437
    gap> FFMatOrPermCMtxBinary( Concatenation( prm, "1a" ) ) = perms[1];
438
    true
439
    gap> FFMatOrPermCMtxBinary( Concatenation( prm, "2b" ) ) = perms[2];
440
    true
441
  
442
  
443
  
444
  7.4 Reading and Writing ATLAS Straight Line Programs
445
  
446
  7.4-1 ScanStraightLineProgram
447
  
448
  ScanStraightLineProgram( filename[, "string"] )  function
449
  Returns:  a record containing the straight line program.
450
  
451
  Let  filename be the name of a file that contains a straight line program in
452
  the sense that it consists only of lines in the following form.
453
  
454
  #anything
455
        lines starting with a hash sign # are ignored,
456
  
457
  echo anything
458
        lines  starting with echo are ignored for the program component of the
459
        result  record  (see  below),  they  are  used to set up the bijection
460
        between  the  labels  used in the program and conjugacy class names in
461
        the case that the program computes dedicated class representatives,
462
  
463
  inp n
464
        means  that  there are n inputs, referred to via the labels 1, 2, ...,
465
        n,
466
  
467
  inp k a1 a2 ... ak
468
        means  that  the  next k inputs are referred to via the labels a1, a2,
469
        ..., ak,
470
  
471
  cjr a b
472
        means that a is replaced by b^(-1) * a * b,
473
  
474
  cj a b c
475
        means that c is defined as b^(-1) * a * b,
476
  
477
  com a b c
478
        means that c is defined as a^(-1) * b^(-1) * a * b,
479
  
480
  iv a b
481
        means that b is defined as a^(-1),
482
  
483
  mu a b c
484
        means that c is defined as a * b,
485
  
486
  pwr a b c
487
        means that c is defined as b^a,
488
  
489
  cp a b
490
        means that b is defined as a copy of a,
491
  
492
  oup l
493
        means that there are l outputs, stored in the labels 1, 2, ..., l, and
494
  
495
  oup l b1 b2 ... bl
496
        means that the next l outputs are stored in the labels b1, b2, ... bl.
497
  
498
  Each  of  the  labels  a,  b,  c  can be any nonempty sequence of digits and
499
  alphabet  characters,  except  that the first argument of pwr must denote an
500
  integer.
501
  
502
  If  the  inp  or  oup  statements  are  missing  then  the  input or output,
503
  respectively,  is  assumed  to  be given by the labels 1 and 2. There can be
504
  multiple inp lines at the beginning of the program and multiple oup lines at
505
  the end of the program. Only the first inp or oup line may omit the names of
506
  the  elements. For example, an empty file filename or an empty string string
507
  represent  a  straight  line  program  with  two inputs that are returned as
508
  outputs.
509
  
510
  No  command except cjr may overwrite its own input. For example, the line mu
511
  a b a is not legal. (This is not checked.)
512
  
513
  ScanStraightLineProgram  returns  a  record  containing  as the value of its
514
  component    program   the   corresponding   GAP   straight   line   program
515
  (see IsStraightLineProgram  (Reference: IsStraightLineProgram)) if the input
516
  string  satisfies the syntax rules stated above, and returns fail otherwise.
517
  In  the  latter  case,  information  about  the  first corrupted line of the
518
  program is printed if the info level of InfoCMeatAxe (7.1-2) is at least 1.
519
  
520
  If  the  string  "string"  is  entered as the second argument then the first
521
  argument  must  be  a  string  as obtained by reading a file in MeatAxe text
522
  format as a text stream (see InputTextFile (Reference: InputTextFile)). Also
523
  in  this  case,  ScanStraightLineProgram  returns  either  a record with the
524
  corresponding GAP straight line program or fail.
525
  
526
  If  the  input describes a straight line program that computes certain class
527
  representatives  of  the  group  in  question  then  the  result record also
528
  contains the component outputs. Its value is a list of strings, the entry at
529
  position  i  denoting  the  name  of  the class in which the i output of the
530
  straight  line program lies; see Section 3.4 for the definition of the class
531
  names that occur.
532
  
533
  Such   straight   line   programs   must  end  with  a  sequence  of  output
534
  specifications of the following form.
535
  
536
    Example  
537
    echo "Classes 1A 2A 3A 5A 5B"
538
    oup 5 3 1 2 4 5
539
  
540
  
541
  This example means that the list of outputs of the program contains elements
542
  of  the  classes 1A, 2A, 3A, 5A, and 5B (in this order), and that inside the
543
  program, these elements are referred to by the five names 3, 1, 2, 4, and 5.
544
  
545
  7.4-2 AtlasStringOfProgram
546
  
547
  AtlasStringOfProgram( prog[, outputnames] )  function
548
  AtlasStringOfProgram( prog[, "mtx"] )  function
549
  Returns:  a string encoding the straight line program/decision in the format
550
            used in ATLAS files.
551
  
552
  For   a   straight   line   program   or   straight   line   decision   prog
553
  (see IsStraightLineProgram     (Reference:     IsStraightLineProgram)    and
554
  IsStraightLineDecision  (6.1-1)),  this function returns a string describing
555
  the  input  format  of  an equivalent straight line program or straight line
556
  decision  as  used in the ATLAS of Group Representations, that is, the lines
557
  are of the form described in ScanStraightLineProgram (7.4-1).
558
  
559
  A  list of strings that is given as the optional second argument outputnames
560
  is  interpreted  as  the  class  names  corresponding  to  the outputs; this
561
  argument  has  the  effect  that  appropriate  echo statements appear in the
562
  result string.
563
  
564
  If  the string "mtx" is given as the second argument then the result has the
565
  format used in the C-MeatAxe (see [Rin]) rather than the format described in
566
  Section 7.4.  (Note  that  the  C-MeatAxe  format does not make sense if the
567
  argument outputnames is given, and that this format does not support inp and
568
  oup statements.)
569
  
570
  The  argument  prog  must  not  be  a  black  box program (see IsBBoxProgram
571
  (6.2-1)).
572
  
573
    Example  
574
    gap> str:= "inp 2\nmu 1 2 3\nmu 3 1 2\niv 2 1\noup 2 1 2";;
575
    gap> prg:= ScanStraightLineProgram( str, "string" );
576
    rec( program := <straight line program> )
577
    gap> prg:= prg.program;;
578
    gap> Display( prg );
579
    # input:
580
    r:= [ g1, g2 ];
581
    # program:
582
    r[3]:= r[1]*r[2];
583
    r[2]:= r[3]*r[1];
584
    r[1]:= r[2]^-1;
585
    # return values:
586
    [ r[1], r[2] ]
587
    gap> StringOfResultOfStraightLineProgram( prg, [ "a", "b" ] );
588
    "[ (aba)^-1, aba ]"
589
    gap> AtlasStringOfProgram( prg );
590
    "inp 2\nmu 1 2 3\nmu 3 1 2\niv 2 1\noup 2\n"
591
    gap> prg:= StraightLineProgram( "(a^2b^3)^-1", [ "a", "b" ] );
592
    <straight line program>
593
    gap> Print( AtlasStringOfProgram( prg ) );
594
    inp 2
595
    pwr 2 1 4
596
    pwr 3 2 5
597
    mu 4 5 3
598
    iv 3 4
599
    oup 1 4
600
    gap> prg:= StraightLineProgram( [ [2,3], [ [3,1,1,4], [1,2,3,1] ] ], 2 );
601
    <straight line program>
602
    gap> Print( AtlasStringOfProgram( prg ) );
603
    inp 2
604
    pwr 3 2 3
605
    pwr 4 1 5
606
    mu 3 5 4
607
    pwr 2 1 6
608
    mu 6 3 5
609
    oup 2 4 5
610
    gap> Print( AtlasStringOfProgram( prg, "mtx" ) );
611
    # inputs are expected in 1 2
612
    zsm pwr3 2 3
613
    zsm pwr4 1 5
614
    zmu 3 5 4
615
    zsm pwr2 1 6
616
    zmu 6 3 5
617
    echo "outputs are in 4 5"
618
    gap> str:= "inp 2\nchor 1 2\nchor 2 3\nmu 1 2 3\nchor 3 5";;
619
    gap> prg:= ScanStraightLineDecision( str );;
620
    gap> AtlasStringOfProgram( prg.program );
621
    "inp 2\nchor 1 2\nchor 2 3\nmu 1 2 3\nchor 3 5\n"
622
  
623
  
624
  
625
  7.5 Data Types Used in the ATLAS of Group Representations
626
  
627
  Each representation or program that is administrated by the AtlasRep package
628
  belongs  to  a  unique  data  type.  Informally,  examples of data types are
629
  permutation  representation,  matrix  representation  over  the integers, or
630
  straight line program for computing class representatives.
631
  
632
  The idea is that for each data type, there can be
633
  
634
      a column of its own in the output produced by DisplayAtlasInfo (3.5-1)
635
        when  called  without  arguments or with only argument a list of group
636
        names,
637
  
638
      a  line  format of its own for the output produced by DisplayAtlasInfo
639
        (3.5-1) when called with first argument a group name,
640
  
641
      an input format of its own for AtlasProgram (3.5-3),
642
  
643
      an input format of its own for OneAtlasGeneratingSetInfo (3.5-5), and
644
  
645
      specific  tests  for  the  data of this data type; these functions are
646
        used by the global tests described in Section 7.8.
647
  
648
  Formally,  a  data  type is defined by a record whose components are used by
649
  the interface functions. The details are described in the following.
650
  
651
  7.5-1 AGR.DeclareDataType
652
  
653
  AGR.DeclareDataType( kind, name, record )  function
654
  
655
  Let  kind  be  one  of  the  strings "rep" or "prg", and record be a record.
656
  AGR.DeclareDataType  declares a new data type of representations (if kind is
657
  "rep")  or  of  programs  (if  kind  is  "prg").  For each group used in the
658
  AtlasRep  package,  the  record that contains the information about the data
659
  will  have  a component name whose value is a list containing the data about
660
  the new type. Examples of name are "perm", "matff", and "classes".
661
  
662
  Mandatory components of record are
663
  
664
  FilenameFormat
665
        This  defines  the format of the filenames containing data of the type
666
        in  question.  The value must be a list that can be used as the second
667
        argument  of AGR.ParseFilenameFormat (7.6-1), such that only filenames
668
        of  the  type  in  question  match.  (It  is  not checked whether this
669
        detection  function  matches exactly one type, so declaring a new type
670
        needs care.)
671
  
672
  AddFileInfo
673
        This  defines  the information stored in the table of contents for the
674
        data  of  the  type.  The  value  must  be a function that takes three
675
        arguments  (the current list of data for the type and the given group,
676
        a list returned by AGR.ParseFilenameFormat (7.6-1) for the given type,
677
        and  a  filename).  This function adds the necessary parts of the data
678
        entry  to  the list, and returns true if the data belongs to the type,
679
        otherwise  false  is returned; note that the latter case occurs if the
680
        filename  matches  the format description but additional conditions on
681
        the parts of the name are not satisfied (for example integer parts may
682
        be required to be positive or prime powers).
683
  
684
  ReadAndInterpretDefault
685
        This is the function that does the work for the default contents value
686
        of  the  accessFunctions  component of AtlasOfGroupRepresentationsInfo
687
        (7.1-6),  see  Section 7.2.  This function must take a path and return
688
        the GAP object given by this file.
689
  
690
  AddDescribingComponents (for rep only)
691
        This  function takes two arguments, a record (that will be returned by
692
        AtlasGenerators   (3.5-2),   OneAtlasGeneratingSetInfo   (3.5-5),   or
693
        AllAtlasGeneratingSetInfos  (3.5-6))  and  the  type record record. It
694
        sets  the components p, dim, id, and ring that are promised for return
695
        values of the abovementioned three functions.
696
  
697
  DisplayGroup (for rep only)
698
        This  defines  the  format  of  the  lines printed by DisplayAtlasInfo
699
        (3.5-1)  for  a given group. The value must be a function that takes a
700
        list  as  returned by the function given in the component AddFileInfo,
701
        and  returns  the  string  to  be  printed  for  the representation in
702
        question.
703
  
704
  Optional components of record are
705
  
706
  DisplayOverviewInfo
707
        This   is   used   to   introduce  a  new  column  in  the  output  of
708
        DisplayAtlasInfo (3.5-1) when this is called without arguments or with
709
        a  list  of group names as its only argument. The value must be a list
710
        of length three, containing at its first position a string used as the
711
        header of the column, at its second position one of the strings "r" or
712
        "l",  denoting  right or left aligned column entries, and at its third
713
        position  a  function  that  takes  two arguments (a list of tables of
714
        contents of the AtlasRep package and a group name), and returns a list
715
        of length two, containing the string to be printed as the column value
716
        and  true  or  false, depending on whether private data is involved or
717
        not.  (The  default  is  fail,  indicating that no new column shall be
718
        printed.)
719
  
720
  DisplayPRG (for prg only)
721
        This is used in DisplayAtlasInfo (3.5-1) for ATLAS programs. The value
722
        must  be  a  function  that  takes four arguments (a list of tables of
723
        contents  to  examine, the name of the given group, a list of integers
724
        or  true for the required standardization, and a list of all available
725
        standardizations),  and  returns  the  list  of  lines (strings) to be
726
        printed as the information about the available programs of the current
727
        type  and  for  the  given  group.  (The default is to return an empty
728
        list.)
729
  
730
  AccessGroupCondition (for rep only)
731
        This is used in DisplayAtlasInfo (3.5-1) and OneAtlasGeneratingSetInfo
732
        (3.5-5). The value must be a function that takes two arguments (a list
733
        as  returned  by  OneAtlasGeneratingSetInfo  (3.5-5),  and  a  list of
734
        conditions), and returns true or false, depending on whether the first
735
        argument  satisfies  the conditions. (The default value is ReturnFalse
736
        (Reference: ReturnFalse).)
737
  
738
        The function must support conditions such as [ IsPermGroup, true ] and
739
        [  NrMovedPoints,  [ 5, 6 ] ], in general a list of functions followed
740
        by  a  prescribed  value, a list of prescribed values, another (unary)
741
        function,  or the string "minimal". For an overview of the interesting
742
        functions, see DisplayAtlasInfo (3.5-1).
743
  
744
  AccessPRG (for prg only)
745
        This  is  used  in  AtlasProgram (3.5-3). The value must be a function
746
        that  takes three arguments (the record with the information about the
747
        given  group in the current table of contents, an integer or a list of
748
        integers  or  true  for  the  required  standardization, and a list of
749
        conditions  given  by the optional arguments of AtlasProgram (3.5-3)),
750
        and  returns  either  fail or a list that together with the group name
751
        forms  the  identifier  of a program that matches the conditions. (The
752
        default value is ReturnFail (Reference: ReturnFail).)
753
  
754
  AtlasProgram (for prg only)
755
        This  is  used in AtlasProgram (3.5-3) to create the result value from
756
        the identifier. (The default value is AtlasProgramDefault, which works
757
        whenever  the  second entry of the identifier is the filename; this is
758
        not  the case for example if the program is the composition of several
759
        programs.)
760
  
761
  AtlasProgramInfo (for prg only)
762
        This  is  used  in AtlasProgramInfo (3.5-4) to create the result value
763
        from the identifier. (The default value is AtlasProgramDefault.)
764
  
765
  TOCEntryString
766
        This is used in StoreAtlasTableOfContents (4.2-2). The value must be a
767
        function  that  takes  two  arguments (the name name of the type and a
768
        list  as  returned  by  AGR.ParseFilenameFormat  (7.6-1) and returns a
769
        string  that  describes  the  appropriate  function call. (The default
770
        value is TOCEntryStringDefault.)
771
  
772
  PostprocessFileInfo
773
        This  is  used  in  the  construction  of  a  table  of  contents  via
774
        ReloadAtlasTableOfContents  (4.2-1),  for  testing  or rearranging the
775
        data  of  the  current table of contents. The value must be a function
776
        that  takes two arguments, the table of contents record and the record
777
        in  it  that  belongs  to  one fixed group. (The default function does
778
        nothing.)
779
  
780
  SortTOCEntries
781
        This  is  used  in  the  construction  of  a  table  of  contents (see
782
        ReloadAtlasTableOfContents  (4.2-1)),  for  sorting  the entries after
783
        they   have   been   added  and  after  the  value  of  the  component
784
        PostprocessFileInfo has been called. The value must be a function that
785
        takes  a  list  as  returned  by  AGR.ParseFilenameFormat (7.6-1), and
786
        returns  the sorting key. (There is no default value, which means that
787
        no sorting is needed.)
788
  
789
  TestFileHeaders (for rep only)
790
        This is used in the function AGR.Test.FileHeaders. The value must be a
791
        function  that  takes  the  same  four  arguments  as AGR.FileContents
792
        (7.6-2),  except that the first argument "datagens" can be replaced by
793
        "local"  and  that  the  third  argument  is  a  list  as  returned by
794
        AGR.ParseFilenameFormat  (7.6-1).  (The  default  value  is ReturnTrue
795
        (Reference: ReturnTrue).)
796
  
797
  TestFiles (for rep only)
798
        This  is  used in the function AGR.Test.Files. The format of the value
799
        and  the  default  are  the  same  as  for  the value of the component
800
        TestFileHeaders.
801
  
802
  TestWords (for prg only)
803
        This  is  used  in  the  function  AGR.Test.Words. The value must be a
804
        function  that  takes five arguments where the first four are the same
805
        arguments  as  for  AGR.FileContents  (7.6-2),  except  that the first
806
        argument "dataword" can be replaced by "local", and the fifth argument
807
        is true or false, indicating verbose mode or not.
808
  
809
  
810
  7.6 Filenames Used in the ATLAS of Group Representations
811
  
812
  The data of each local GAP version of the ATLAS of Group Representations are
813
  either private (see Chapter 5) or are stored in the two directories datagens
814
  and  dataword.  In the following, we describe the format of filenames in the
815
  latter two directories, as a reference of the official part of the ATLAS.
816
  
817
  In  the directory datagens, the generators for the representations available
818
  are  stored,  the  directory  dataword  contains  the  programs  to  compute
819
  conjugacy  class representatives, generators of maximal subgroups, images of
820
  generators  under  automorphisms of a given group G from standard generators
821
  of G, and to check and compute standard generators (see Section 3.3).
822
  
823
  The  name  of each data file in the ATLAS of Group Representations describes
824
  the  contents  of  the  file.  This  section  lists  the  definitions of the
825
  filenames used.
826
  
827
  Each  filename consists of two parts, separated by a minus sign -. The first
828
  part is always of the form groupnameGi, where the integer i denotes the i-th
829
  set  of  standard  generators  for  the  group  G, say, with ATLAS-file name
830
  groupname  (see 3.2).  The translations of the name groupname to the name(s)
831
  used    within    GAP    is    given    by   the   component   GAPnames   of
832
  AtlasOfGroupRepresentationsInfo (7.1-6).
833
  
834
  The  filenames in the directory dataword have one of the following forms. In
835
  each of these cases, the suffix Wn means that n is the version number of the
836
  program.
837
  
838
  groupnameGi-cycWn
839
        In this case, the file contains a straight line program that returns a
840
        list of representatives of generators of maximally cyclic subgroups of
841
        G. An example is Co1G1-cycW1.
842
  
843
  groupnameGi-cclsWn
844
        In this case, the file contains a straight line program that returns a
845
        list   of   conjugacy  class  representatives  of  G.  An  example  is
846
        RuG1-cclsW1.
847
  
848
  groupnameGicycWn-cclsWm
849
        In this case, the file contains a straight line program that takes the
850
        return value of the program in the file groupnameGi-cycWn (see above),
851
        and returns a list of conjugacy class representatives of G. An example
852
        is M11G1cycW1-cclsW1.
853
  
854
  groupnameGi-maxkWn
855
        In  this  case,  the  file contains a straight line program that takes
856
        generators  of  G  w.r.t. the  i-th  set  of  standard generators, and
857
        returns  a list of generators (in general not standard generators) for
858
        a  subgroup  U in the k-th class of maximal subgroups of G. An example
859
        is J1G1-max7W1.
860
  
861
  groupnameGimaxkWn-subgroupnameGjWm
862
        In this case, the file contains a straight line program that takes the
863
        return  value  of  the  program  in  the  file groupnameGi-maxkWn (see
864
        above),  which  are  generators  for a group U, say; subgroupname is a
865
        name  for U, and the return value is a list of standard generators for
866
        U, w.r.t. the j-th set of standard generators. (Of course this implies
867
        that  the  groups  in  the  k-th  class  of maximal subgroups of G are
868
        isomorphic  to  the  group  with  name  subgroupname.)  An  example is
869
        J1G1max1W1-L211G1W1; the first class of maximal subgroups of the Janko
870
        group  J_1  consists of groups isomorphic to the linear group L_2(11),
871
        for which standard generators are defined.
872
  
873
  groupnameGi-aoutnameWn
874
        In  this  case,  the  file contains a straight line program that takes
875
        generators  of  G  w.r.t. the  i-th  set  of  standard generators, and
876
        returns  the  list of their images under the outer automorphism α of G
877
        given  by the name outname; if this name is empty then α is the unique
878
        nontrivial outer automorphism of G; if it is a positive integer k then
879
        α  is  a  generator of the unique cyclic order k subgroup of the outer
880
        automorphism  group  of  G; if it is of the form 2_1 or 2a, 4_2 or 4b,
881
        3_3  or  3c  ...  then  α  generates the cyclic group of automorphisms
882
        induced on G by G.2_1, G.4_2, G.3_3 ...; finally, if it is of the form
883
        kpd, with k one of the above forms and d an integer then d denotes the
884
        number of dashes appended to the automorphism described by k; if d = 1
885
        then   d   can   be  omitted.  Examples  are  A5G1-aW1,  L34G1-a2_1W1,
886
        U43G1-a2_3pW1,  and  O8p3G1-a2_2p5W1;  these  file  names describe the
887
        outer  order  2 automorphism of A_5 (induced by the action of S_5) and
888
        the  order  2 automorphisms of L_3(4), U_4(3), and O_8^+(3) induced by
889
        the  actions  of  L_3(4).2_1,  U_4(3).2_2^', and O_8^+(3).2_2^{'''''},
890
        respectively.
891
  
892
  groupnameGi-GjWn
893
        In  this  case,  the  file contains a straight line program that takes
894
        generators  of  G  w.r.t. the  i-th  set  of  standard generators, and
895
        returns  standard  generators  of  G  w.r.t. the  j-th set of standard
896
        generators. An example is L35G1-G2W1.
897
  
898
  groupnameGi-checkn
899
        In  this  case,  the file contains a straight line decision that takes
900
        generators  of  G,  and  returns true if these generators are standard
901
        generators w.r.t. the i-th standardization, and false otherwise.
902
  
903
  groupnameGi-Pn
904
        In  this  case,  the file contains a straight line decision that takes
905
        some  group  elements, and returns true if these elements are standard
906
        generators   for   G,   w.r.t. the  i-th  standardization,  and  false
907
        otherwise.
908
  
909
  groupnameGi-findn
910
        In  this  case,  the  file  contains  a black box program that takes a
911
        group,  and returns (if it is successful) a set of standard generators
912
        for G, w.r.t. the i-th standardization.
913
  
914
  groupnameGi-XdescrWn
915
        In  this  case,  the  file contains a straight line program that takes
916
        generators  of G w.r.t. the i-th set of standard generators, and whose
917
        return value corresponds to descr. This format is used only in private
918
        extensions  (see  Chapter 5), such a script can be accessed with descr
919
        as the third argument of AtlasProgram (3.5-3).
920
  
921
  The  filenames in the directory datagens have one of the following forms. In
922
  each  of  these  cases,  id  is a (possibly empty) string that starts with a
923
  lowercase      alphabet     letter     (see IsLowerAlphaChar     (Reference:
924
  IsLowerAlphaChar)),  and  m  is  a  nonnegative  integer,  meaning  that the
925
  generators  are written w.r.t. the m-th basis (the meaning is defined by the
926
  ATLAS developers).
927
  
928
  groupnameGi-fqrdimidBm.mnr
929
        a file in MeatAxe text file format containing the nr-th generator of a
930
        matrix  representation  over  the  field with q elements, of dimension
931
        dim. An example is S5G1-f2r4aB0.m1.
932
  
933
  groupnameGi-pnidBm.mnr
934
        a file in MeatAxe text file format containing the nr-th generator of a
935
        permutation representation on n points. An example is M11G1-p11B0.m1.
936
  
937
  groupnameGi-ArdimidBm.g
938
        a   GAP   readable   file   containing  all  generators  of  a  matrix
939
        representation  of  dimension  dim  over an algebraic number field not
940
        specified further. An example is A5G1-Ar3aB0.g.
941
  
942
  groupnameGi-ZrdimidBm.g
943
        a   GAP   readable   file   containing  all  generators  of  a  matrix
944
        representation  over  the  integers,  of  dimension dim. An example is
945
        A5G1-Zr4B0.g.
946
  
947
  groupnameGi-HrdimidBm.g
948
        a   GAP   readable   file   containing  all  generators  of  a  matrix
949
        representation  over  a  quaternion  algebra  over an algebraic number
950
        field, of dimension dim. An example is 2A6G1-Hr2aB0.g.
951
  
952
  groupnameGi-ZnrdimidBm.g
953
        a   GAP   readable   file   containing  all  generators  of  a  matrix
954
        representation  of  dimension  dim over the ring of integers mod n. An
955
        example is 2A8G1-Z4r4aB0.g.
956
  
957
  7.6-1 AGR.ParseFilenameFormat
958
  
959
  AGR.ParseFilenameFormat( string, format )  function
960
  Returns:  a  list of strings and integers if string matches format, and fail
961
            otherwise.
962
  
963
  Let  string  be a filename, and format be a list [ [ c_1, c_2, ..., c_n ], [
964
  f_1,  f_2, ..., f_n ] ] such that each entry c_i is a list of strings and of
965
  functions  that take a character as their argument and return true or false,
966
  and  such  that each entry f_i is a function for parsing a filename, such as
967
  the currently undocumented functions ParseForwards and ParseBackwards.
968
  
969
  AGR.ParseFilenameFormat returns a list of strings and integers such that the
970
  concatenation  of  their  String (Reference: String) values yields string if
971
  string  matches  format, and fail otherwise. Matching is defined as follows.
972
  Splitting  string  at each minus character (-) yields m parts s_1, s_2, ...,
973
  s_m.  The string string matches format if s_i matches the conditions in c_i,
974
  for  1  ≤  i  ≤  n,  in  the sense that applying f_i to s_i and c_i yields a
975
  non-fail result.
976
  
977
    Example  
978
    gap> format:= [ [ [ IsChar, "G", IsDigitChar ],
979
    >                 [ "p", IsDigitChar, AGR.IsLowerAlphaOrDigitChar,
980
    >                   "B", IsDigitChar, ".m", IsDigitChar ] ],
981
    >               [ ParseBackwards, ParseForwards ] ];;
982
    gap> AGR.ParseFilenameFormat( "A6G1-p10B0.m1", format );
983
    [ "A6", "G", 1, "p", 10, "", "B", 0, ".m", 1 ]
984
    gap> AGR.ParseFilenameFormat( "A6G1-p15aB0.m1", format );
985
    [ "A6", "G", 1, "p", 15, "a", "B", 0, ".m", 1 ]
986
    gap> AGR.ParseFilenameFormat( "A6G1-f2r16B0.m1", format );
987
    fail
988
  
989
  
990
  7.6-2 AGR.FileContents
991
  
992
  AGR.FileContents( dirname, groupname, filename, type )  function
993
  Returns:  the  GAP object obtained from reading and interpreting the file(s)
994
            with name(s) filename.
995
  
996
  Let  dirname  and  groupname  be  strings, filename be a string or a list of
997
  strings,  and type be a data type (see AGR.DeclareDataType (7.5-1)). dirname
998
  must  be  one  of  "datagens",  "dataword",  or the dirid value of a private
999
  directory, see AtlasOfGroupRepresentationsNotifyPrivateDirectory (5.1-1). If
1000
  groupname  is  the  ATLAS-file  name  of a group G (see Section 3.2), and if
1001
  filename  is  either the name of an accessible file in the dirname directory
1002
  of  the  ATLAS,  or a list of such filenames, with data concerning G and for
1003
  the  data  type  type,  then  AGR.FileContents  returns  the contents of the
1004
  corresponding  file(s),  in  the sense that the file(s) (or equivalent ones,
1005
  see  Section 4.3-6) is/are read, and the result is interpreted if necessary;
1006
  otherwise fail is returned.
1007
  
1008
  Note  that  if  filename  refers  to  file(s)  already stored in the dirname
1009
  directory then AGR.FileContents does not check whether the table of contents
1010
  of the ATLAS of Group Representations actually contains filename.
1011
  
1012
  
1013
  7.7 The Tables of Contents of the ATLAS of Group Representations
1014
  
1015
  The  list  of  data  currently  available  is  stored  in  several tables of
1016
  contents,  one  for  the local GAP data, one for the data on remote servers,
1017
  and  one  for  each  private  data  directory.  These tables of contents are
1018
  created by ReloadAtlasTableOfContents (4.2-1).
1019
  
1020
  It  is  assumed  that the local data directories contain only files that are
1021
  also   available  on  servers.  Private  extensions  to  the  database  (cf.
1022
  Section 4.5  and Chapter 5) cannot be handled by putting the data files into
1023
  the local directories.
1024
  
1025
  Each  table  of contents is represented by a record whose components are the
1026
  ATLAS-file  names  of the groups (see Section 3.2) and lastupdated, a string
1027
  describing  the date of the last update of this table of contents. The value
1028
  for each group name is a record whose components are the names of those data
1029
  types (see Section 7.5) for which data are available.
1030
  
1031
  Here are the administrational functions that are used to build the tables of
1032
  contents.  Some  of  them  may  be useful also for private extensions of the
1033
  package (see Chapter 5).
1034
  
1035
  The  following  functions define group names, available representations, and
1036
  straight line programs.
1037
  
1038
  AGR.GNAN( gapname, atlasname )
1039
        Called  with  two  strings  gapname  (the  GAP  name of the group) and
1040
        atlasname   (the  ATLAS  name  of  the  group),  AGR.GNAN  stores  the
1041
        information   in  the  list  AtlasOfGroupRepresentationsInfo.GAPnames,
1042
        which  defines  the name mapping between the ATLAS names and GAP names
1043
        of the groups.
1044
  
1045
        This function may be used also for private extensions of the database.
1046
  
1047
        An example of a valid call is AGR.GNAN("A5.2","S5").
1048
  
1049
  AGR.GRP( dirname, simpname, groupname)
1050
        Called  with  three strings, AGR.GRP stores in the groupname component
1051
        of  AtlasOfGroupRepresentationsInfo  (7.1-6)  in  which  path  on  the
1052
        servers  the  data  about  the  group with ATLAS name groupname can be
1053
        found.
1054
  
1055
        This function is not intended for private extensions of the database.
1056
  
1057
        An example of a valid call is AGR.GRP("alt","A5","S5").
1058
  
1059
  AGR.TOC( typename, filename, crcfile )
1060
        Called  with  two  strings  typename  and  filename, and a list crc of
1061
        integers,  AGR.TOC  notifies  an  entry  to the TableOfContents.remote
1062
        component  of  AtlasOfGroupRepresentationsInfo (7.1-6), where typename
1063
        must be the name of the data type to which the entry belongs, filename
1064
        must  be  the  prefix of the data file(s), and crc must be the list of
1065
        CrcFile (Reference: CrcFile) values of the file(s).
1066
  
1067
        This function is not intended for private extensions of the database.
1068
  
1069
        An        example        of        a        valid        call       is
1070
        AGR.TOC("perm","S5G1-p5B0.m",[-3581724,115937465]).
1071
  
1072
  The  following  functions  add  data  about  the  groups  and their standard
1073
  generators.  The  function  calls  must  be executed after the corresponding
1074
  AGR.GNAN calls.
1075
  
1076
  AGR.GRS( gapname, size )
1077
        Called  with  the  string  gapname (the GAP name of the group) and the
1078
        integer size (the order of the group), AGR.GRS stores this information
1079
        in AtlasOfGroupRepresentationsInfo.GAPnames.
1080
  
1081
        An example of a valid call is AGR.GRS("A5.2",120).
1082
  
1083
  AGR.MXN( gapname, nrMaxes )
1084
        Called  with  the  string  gapname (the GAP name of the group) and the
1085
        integer  nrMaxes  (the  number  of classes of maximal subgroups of the
1086
        group),       AGR.MXN       stores       the       information      in
1087
        AtlasOfGroupRepresentationsInfo.GAPnames.
1088
  
1089
        An example of a valid call is AGR.MXN("A5.2",4).
1090
  
1091
  AGR.MXO( gapname, sizesMaxes )
1092
        Called  with  the  string  gapname (the GAP name of the group) and the
1093
        list  sizesMaxes  (of  subgroup  orders  of  the  classes  of  maximal
1094
        subgroups  of  the  group,  not  necessarily  dense, in non-increasing
1095
        order),       AGR.MXO       stores       the       information      in
1096
        AtlasOfGroupRepresentationsInfo.GAPnames.
1097
  
1098
        An example of a valid call is AGR.MXO("A5.2",[60,24,20,12]).
1099
  
1100
  AGR.MXS( gapname, structureMaxes )
1101
        Called  with  the  string  gapname (the GAP name of the group) and the
1102
        list  structureMaxes  (of  strings  describing  the  structures of the
1103
        maximal subgroups of the group, not necessarily dense), AGR.MXS stores
1104
        the information in AtlasOfGroupRepresentationsInfo.GAPnames.
1105
  
1106
        An        example        of        a        valid        call       is
1107
        AGR.MXS("A5.2",["A5","S4","5:4","S3x2"]).
1108
  
1109
  AGR.KERPRG( gapname, kernelProgram )
1110
        Called  with  the  string  gapname (the GAP name of the group) and the
1111
        list kernelProgram (with entries the standardization of the group, the
1112
        GAP  name  of a factor group, and the list of lines of a straight line
1113
        program that computes generators of the kernel of the epimorphism from
1114
        the  group  to the factor group), AGR.KERPRG stores the information in
1115
        AtlasOfGroupRepresentationsInfo.GAPnames.
1116
  
1117
        An example of a valid call is AGR.KERPRG("2.J2",[1,"J2",[[[1,2]]]]).
1118
  
1119
  AGR.STDCOMP
1120
        Called  with  the  string  gapname (the GAP name of the group) and the
1121
        list  factorCompatibility  (with  entries  the  standardization of the
1122
        group,  the  GAP  name  of a factor group, the standardization of this
1123
        factor  group,  and  true  or  false,  indicating  whether mapping the
1124
        standard  generators  for  gapname  to those of factgapname defines an
1125
        epimorphism),     AGR.STDCOMP     stores     the     information    in
1126
        AtlasOfGroupRepresentationsInfo.GAPnames.
1127
  
1128
        An example of a valid call is AGR.STDCOMP("2.A5.2",[1,"A5.2",1,true]).
1129
  
1130
  The  following  functions  add  data  about representations or straight line
1131
  programs  that  are already known. The function calls must be executed after
1132
  the corresponding AGR.TOC calls.
1133
  
1134
  AGR.RNG( repname, descr )
1135
        Called  with  two  strings  repname  (denoting  the  name  of  a  file
1136
        containing  the generators of a matrix representation over a ring that
1137
        is  not determined by the filename) and descr (describing this ring R,
1138
        say), AGR.RNG adds the triple [ repname, descr, R ] to the list stored
1139
        in the ringinfo component of AtlasOfGroupRepresentationsInfo (7.1-6).
1140
  
1141
        An        example        of        a        valid        call       is
1142
        AGR.RNG("A5G1-Ar3aB0","Field([Sqrt(5)])").
1143
  
1144
  AGR.TOCEXT( atlasname, std, maxnr, files )
1145
        Called  with  the  string atlasname (the ATLAS name of the group), the
1146
        positive  integers  std (the standardization) and maxnr (the number of
1147
        the  class  of maximal subgroups), and the list files (of filenames of
1148
        straight  line  programs  for  computing  generators  of  the maxnr-th
1149
        maximal  subgroup,  using  a  straight line program for a factor group
1150
        plus   perhaps   some  straight  line  program  for  computing  kernel
1151
        generators), AGR.TOCEXT stores the information in the maxext component
1152
        of the atlasname component of the "remote" table of contents.
1153
  
1154
        An example of a valid call is AGR.TOCEXT("2A5",1,3,["A5G1-max3W1"]).
1155
  
1156
  AGR.API( repname, info )
1157
        Called  with  the  string  repname (denoting the name of a permutation
1158
        representation)  and the list info (describing the point stabilizer of
1159
        this  representation),  AGR.API  binds  the  component  repname of the
1160
        record AtlasOfGroupRepresentationsInfo.permrepinfo to info.
1161
  
1162
        info has the following entries.
1163
  
1164
            At position 1, the transitivity is stored.
1165
  
1166
            If the transitivity is zero then the second entry is the list of
1167
              orbit lengths.
1168
  
1169
            If  the  transitivity  is  positive then the second entry is the
1170
              rank of the action.
1171
  
1172
            If  the  transitivity is positive then the third entry is one of
1173
              the strings "prim", "imprim", denoting primitivity or not.
1174
  
1175
            If  the  transitivity  is  positive  then  the fourth entry is a
1176
              string  describing the structure of the point stabilizer. If the
1177
              third  entry  is  "imprim"  then  this description consists of a
1178
              subgroup part and a maximal subgroup part, separated by " < ".
1179
  
1180
            If  the  third  entry  is  "prim" then the fifth entry is either
1181
              "???" or it denotes the number of the class of maximal subgroups
1182
              that are the point stabilizers.
1183
  
1184
        An        example        of        a        valid        call       is
1185
        AGR.API("A5G1-p5B0",[3,2,"prim","A4",1]).
1186
  
1187
  AGR.CHAR( groupname, repname, char, pos[, charname] )
1188
        Called  with  the  strings  groupname  (the GAP name of the group) and
1189
        repname  (denoting  the  name of the representation), the integer char
1190
        (the  characteristic  of the representation), and pos (the position or
1191
        list  of positions of the irreducible constituent(s)), AGR.CHAR stores
1192
        the  information  in  AtlasOfGroupRepresentationsInfo.characterinfo. A
1193
        string describing the character can be entered as charname.
1194
  
1195
        An        example        of        a        valid        call       is
1196
        AGR.CHAR("M11","M11G1-p11B0",0,[1,2],"1a+10a").
1197
  
1198
  These  functions  are  used  to create the initial table of contents for the
1199
  server  data  of  the  AtlasRep  package when the file gap/atlasprm.g of the
1200
  package is read.
1201
  
1202
  
1203
  7.8 Sanity Checks for the ATLAS of Group Representations
1204
  
1205
  The  fact  that  the  ATLAS  of Group Representations is designed as an open
1206
  database   (see   Section 4.3-1)  makes  it  especially  desirable  to  have
1207
  consistency  checks  available  which  can be run automatically whenever new
1208
  data  are  added  by  the  developers  of  the ATLAS. The tests described in
1209
  Section  7.8-1  can  be  used  also  for data from private extensions of the
1210
  package  (see  Chapter 5),  Section 7.8-2 lists tests which do not have this
1211
  property.
1212
  
1213
  All  these tests apply only to the local table of contents (see Section 7.7)
1214
  or  to  private  extensions.  So  only those data files are checked that are
1215
  actually  available in the local GAP installation. No files are fetched from
1216
  servers  during  these  tests. The required space and time for running these
1217
  tests depend on the amount of locally available data.
1218
  
1219
  The  file  tst/testall.g  of  the  package  contains  Test (Reference: Test)
1220
  statements  for  executing  a  collection of such sanity checks; one can run
1221
  them  by  calling  ReadPackage( "AtlasRep", "tst/testall.g" ). If no problem
1222
  occurs then GAP prints only lines starting with one of the following.
1223
  
1224
    Example  
1225
    + Input file:
1226
    + GAP4stones:
1227
  
1228
  
1229
  Some  of  the checks compute and verify additional data, such as information
1230
  about  point  stabilizers  of  permutation  representations. In these cases,
1231
  output   lines   starting   with   #E  are  error  messages  that  point  to
1232
  inconsistencies,  whereas  output  lines  starting with #I inform about data
1233
  that  have  been computed and were not yet stored, or about stored data that
1234
  were not verified.
1235
  
1236
  The  examples  in  the  package  manual  form  a part of the tests, they are
1237
  collected in the file tst/docxpl.tst of the package.
1238
  
1239
  
1240
  7.8-1 Sanity Checks for a Table of Contents
1241
  
1242
  The  following  tests  can  be used to check the data that belong to a given
1243
  table  of contents. Each of these tests is given by a function with optional
1244
  argument  tocid,  the identifying string that had been entered as the second
1245
  argument  of  AtlasOfGroupRepresentationsNotifyPrivateDirectory (5.1-1). The
1246
  contents of the local dataword directory can be checked by entering "local",
1247
  which  is also the default for tocid. The function returns false if an error
1248
  occurs,  otherwise  true.  Currently  the  following  tests of this kind are
1249
  available.
1250
  
1251
  AGR.Test.Words( [tocid] )
1252
        processes  all straight line programs that are stored in the directory
1253
        with  identifier  tocid,  using  the  function stored in the TestWords
1254
        component of the data type in question.
1255
  
1256
  AGR.Test.FileHeaders( [tocid] )
1257
        checks  whether  all  MeatAxe  text format data files in the directory
1258
        with  identifier  tocid have a header line that is consistent with the
1259
        filename,  and  whether  the  contents of all GAP format data files in
1260
        this directory is consistent with the contents of the file.
1261
  
1262
  AGR.Test.Files( [tocid] )
1263
        checks whether the MeatAxe text files that are stored in the directory
1264
        with  identifier  tocid  can be read with ScanMeatAxeFile (7.3-1) such
1265
        that  the  result is not fail. The function does not check whether the
1266
        first  line  of  a  MeatAxe text file is consistent with the filename,
1267
        since this can be tested with AGR.Test.FileHeaders.
1268
  
1269
  AGR.Test.BinaryFormat( [tocid] )
1270
        checks  whether  all  MeatAxe  text format data files in the directory
1271
        with     identifier     tocid     satisfy    that    applying    first
1272
        CMtxBinaryFFMatOrPerm  (7.3-4)  and then FFMatOrPermCMtxBinary (7.3-5)
1273
        yields the same object.
1274
  
1275
  AGR.Test.Primitivity( [tocid] )
1276
        checks   the   stored  primitivity  information  for  the  permutation
1277
        representations  that  are  stored  in  the  directory with identifier
1278
        tocid.
1279
  
1280
  AGR.Test.Characters( [tocid] )
1281
        checks the stored character information for the matrix and permutation
1282
        representations  that  are  stored  in  the  directory with identifier
1283
        tocid.
1284
  
1285
  
1286
  7.8-2 Other Sanity Checks
1287
  
1288
  The  tests described in this section are not intended for checking data from
1289
  private  extensions of the AtlasRep package. Each of the tests is given by a
1290
  function  without  arguments that returns false if a contradiction was found
1291
  during  the  test,  and  true  otherwise. Additionally, certain messages are
1292
  printed when contradictions between stored and computed data are found, when
1293
  stored  data  cannot  be  verified computationally, or when the computations
1294
  yield improvements of the stored data. Currently the following tests of this
1295
  kind are available.
1296
  
1297
  AGR.Test.GroupOrders()
1298
        checks  whether  the  group orders stored in the GAPnames component of
1299
        AtlasOfGroupRepresentationsInfo (7.1-6) coincide with the group orders
1300
        computed  from  an  ATLAS  permutation  representation of degree up to
1301
        AGR.Test.MaxTestDegree, from the character table or the table of marks
1302
        with the given name, or from the structure of the name. Supported is a
1303
        splitting of the name at the first dot (.), where the two parts of the
1304
        name  are examined with the same criteria in order to derive the group
1305
        order.
1306
  
1307
  AGR.Test.MaxesOrders()
1308
        checks whether the orders of maximal subgroups stored in the component
1309
        GAPnames  of AtlasOfGroupRepresentationsInfo (7.1-6) coincide with the
1310
        orders   computed   from  the  restriction  of  an  ATLAS  permutation
1311
        representation  of  degree  up  to  AGR.Test.MaxTestDegree,  from  the
1312
        character  table,  or  the table of marks with the given name, or from
1313
        the  information  about  maximal  subgroups of a factor group modulo a
1314
        normal subgroup that is contained in the Frattini subgroup.
1315
  
1316
  AGR.Test.MaxesStructure()
1317
        checks  whether the names of maximal subgroups stored in the component
1318
        GAPnames  of AtlasOfGroupRepresentationsInfo (7.1-6) coincide with the
1319
        names computed from the GAP character table with the given name.
1320
  
1321
  AGR.Test.StdCompatibility()
1322
        checks  whether  the  information  about the compatibility of standard
1323
        generators  of  a  group  and  its factor groups that is stored in the
1324
        GAPnames    component   of   AtlasOfGroupRepresentationsInfo   (7.1-6)
1325
        coincides with computed values.
1326
  
1327
        The following criterion is used for computing the value for a group G.
1328
        Use  the GAP Character Table Library to determine factor groups F of G
1329
        for  which standard generators are defined and moreover a presentation
1330
        in  terms of these standard generators is known. Evaluate the relators
1331
        of  the presentation in the standard generators of G, and let N be the
1332
        normal  closure  of  these  elements  in  G. Then mapping the standard
1333
        generators  of F to the N-cosets of the standard generators of G is an
1334
        epimorphism.  If  |G/N| = |F| holds then G/N and F are isomorphic, and
1335
        the  standard  generators  of G and F are compatible in the sense that
1336
        mapping the standard generators of G to their N-cosets yields standard
1337
        generators of F.
1338
  
1339
  AGR.Test.CompatibleMaxes()
1340
        checks  whether  the information about deriving straight line programs
1341
        for  restricting  to subgroups from straight line programs that belong
1342
        to a factor group coincide with computed values.
1343
  
1344
        The following criterion is used for computing the value for a group G.
1345
        If F is a factor group of G such that the standard generators of G and
1346
        F are compatible (see the test function AGR.Test.StdCompatibility) and
1347
        if  there are a presentation for F and a permutation representation of
1348
        G  then  it is checked whether the "maxes" type straight line programs
1349
        for  F  can be used to compute generators for the maximal subgroups of
1350
        G;  if  not  then  generators of the kernel of the natural epimorphism
1351
        from G to F, must be added.
1352
  
1353
  AGR.Test.ClassScripts()
1354
        checks whether the straight line programs that compute representatives
1355
        of certain conjugacy classes are consistent with information stored on
1356
        the  GAP  character  table of the group in question, in the sense that
1357
        the given class names really occur in the character table and that the
1358
        element orders and centralizer orders for the classes are correct.
1359
  
1360
  AGR.Test.CycToCcls()
1361
        checks    whether   some   straight   line   program   that   computes
1362
        representatives  of  conjugacy classes of a group can be computed from
1363
        the  ordinary  GAP  character  table of that group and a straight line
1364
        program  that  computes  representatives  of cyclic subgroups. In this
1365
        case  the  missing  scripts  are  printed if the level of InfoAtlasRep
1366
        (7.1-1) is at least 1.
1367
  
1368
  AGR.Test.Standardization()
1369
        checks  whether  all  generating sets corresponding to the same set of
1370
        standard  generators  have  the same element orders; for the case that
1371
        straight line programs for computing certain class representatives are
1372
        available,  also  the  orders  of  these  representatives  are checked
1373
        w. r. t. all generating sets.
1374
  
1375
  AGR.Test.StdTomLib()
1376
        checks  whether the standard generators are compatible with those that
1377
        occur in the TomLib package.
1378
  
1379
  AGR.Test.KernelGenerators()
1380
        checks  whether  the  information  stored in the GAPnames component of
1381
        AtlasOfGroupRepresentationsInfo  (7.1-6)  about straight line programs
1382
        for  computing  generators  of  the  kernels  of  natural epimorphisms
1383
        between ATLAS groups coincides with computed values.
1384
  
1385
        The following criterion is used for computing the value for a group G.
1386
        Use  the GAP Character Table Library to determine factor groups F of G
1387
        for  which  standard generators are defined such that mapping standard
1388
        generators  of G to those of F defines a homomorphism, and such that a
1389
        presentation  of  F  in  terms  of  its  standard generators is known.
1390
        Evaluating the relators of the presentation in the standard generators
1391
        of G yields normal subgroup generators for the kernel.
1392
  
1393
        A  message is printed for each group name for which some straight line
1394
        program  for  computing  kernel  generators was not stored but now was
1395
        computed, or for which the stored info cannot be verified,
1396
  
1397
  AGR.Test.MinimalDegrees()
1398
        checks  that the (permutation and matrix) representations available in
1399
        the ATLAS of Group Representations do not have smaller degree than the
1400
        claimed minimum.
1401
  
1402

1403