5 Technicalities of the AtlasRep Package
  
  This  chapter  describes  those  parts  of the GAP interface to the ATLAS of
  Group   Representations   that   do   not   belong  to  the  user  interface
  (cf. Chapter 2).
  
  Besides   global   variables   used   for   administrational  purposes  (see
  Section 5.1)  and  several  sanity  checks  (see  Section 5.8),  they can be
  regarded  as  the interface between the data actually contained in the files
  and  the corresponding GAP objects (see Section 5.2, 5.3, 5.4, and 5.5), and
  the  interface between the remote and the local version of the database (see
  Section 5.6  and 5.7).  The  former interface contains functions to read and
  write  files  in MeatAxe format, which may be interesting for users familiar
  with   MeatAxe  standalones  (see  for  example [Rin98]).  Other  low  level
  functions  may  be  undocumented in the sense that they are not described in
  this  manual. Users interested in them may look at the actual implementation
  in  the  gap  directory  of the package, but it may happen that this will be
  changed in future versions of the package.
  
  
  5.1 Global Variables Used by the AtlasRep Package
  
  For debugging purposes, the functions from the GAP interface to the ATLAS of
  Group  Representations  print information depending on the info level of the
  info  classes  InfoAtlasRep  (5.1-1),  InfoCMeatAxe  (5.1-2),  and  InfoBBox
  (5.1-3) (cf. 'Reference: Info Functions').
  
  The  info  level  of  an  info  class  can  be  changed  using  SetInfoLevel
  (Reference:  SetInfoLevel).  For  example,  the  info  level of InfoAtlasRep
  (5.1-1)  can  be  set  to  the  nonnegative  integer  n  using SetInfoLevel(
  InfoAtlasRep, n ).
  
  Information  about  files being read can be obtained by setting the value of
  the global variable InfoRead1 to Print (Reference: Print).
  
  5.1-1 InfoAtlasRep
  
  > InfoAtlasRep____________________________________________________info class
  
  If  the info level of InfoAtlasRep is at least 1 then information about fail
  results  of  functions in the AtlasRep package is printed. If the info level
  is  at least 2 then information about calls to external programs is printed.
  The default level is 0, no information is printed on this level.
  
  5.1-2 InfoCMeatAxe
  
  > InfoCMeatAxe____________________________________________________info class
  
  If  the info level of InfoCMeatAxe is at least 1 then information about fail
  results  of  C-MeatAxe  functions  is printed. The default level is zero, no
  information is printed on this level.
  
  5.1-3 InfoBBox
  
  > InfoBBox________________________________________________________info class
  
  If  the  info  level  of  InfoBBox is at least 1 then information about fail
  results  of  functions  dealing with black box programs (see Section 4.2) is
  printed. The default level is 0, no information is printed on this level.
  
  5.1-4 CMeatAxe.FastRead
  
  > CMeatAxe.FastRead__________________________________________global variable
  
  If  this  component  is  bound  and  has the value true then ScanMeatAxeFile
  (5.3-1) reads text files via StringFile (GAPDoc: StringFile). Otherwise each
  file  containing  a  matrix  over  a  finite  field is read line by line via
  ReadLine  (Reference:  ReadLine),  and the GAP matrix is constructed line by
  line,  in  a  compressed  representation  (see 'Reference:  Row Vectors over
  Finite Fields' and 'Reference: Matrices over Finite Fields'), which makes it
  possible  to  read  large  matrices  in  a  reasonable  amount of space. The
  StringFile   (GAPDoc:   StringFile)   approach  is  faster  but  needs  more
  intermediate  space  when  text files containing matrices over finite fields
  are read.
  
  5.1-5 AtlasOfGroupRepresentationsInfo
  
  > AtlasOfGroupRepresentationsInfo____________________________global variable
  
  This  is  a  record  that is defined in the file gap/types.g of the package,
  with the following components.
  
  Components corresponding to user parameters (see Section 1.7) are
  
  remote
        a boolean that controls what files are available; if the value is true
        then  GAP is allowed to try remotely accessing any ATLAS file from the
        servers  (see  below) and thus all files listed in the global table of
        contents are available, if the value is false then GAP may access only
        those  files  that are stored in the database directories of the local
        GAP installation (see Section 1.7-1),
  
  servers
        a  list  of  pairs [ server, path ], where server is a string denoting
        the  http  address of a server where files can be fetched that are not
        stored in the local database, and path is a string describing the path
        where the data directories on the server reside,
  
  wget
        a  boolean  that  controls  whether  the  GAP package IO[Neu07] or the
        external program wget is used to fetch data files, see 1.7-3,
  
  compress
        a  boolean  that controls whether MeatAxe format text files are stored
        in  compressed  form;  if  the  value  is  true  then  these files are
        compressed  with  gzip after they have been fetched from a server, see
        Section 1.7-4,
  
  displayFunction
        the function that is used by DisplayAtlasInfo (2.5-1) for printing the
        formatted data, see Section 1.7-5,
  
  accessFunctions
        a  list  of records, each describing how to access the data files, see
        Sections 1.7-6 and 5.2.
  
  markprivate
        a  string  used  in DisplayAtlasInfo (2.5-1) to mark private data, see
        Section  3.2, and
  
  System components (which are computed automatically) are
  
  GAPnames
        a  list of pairs, each containing the GAP name and the ATLAS-file name
        of a group, see Section 2.2,
  
  groupnames
        a  list  of triples, each containing at the first position the name of
        the  directory  on each server that contains data about the group G in
        question,  at  the  second  position  the name of the (usually simple)
        group  for which a subdirectory exists that contains the data about G,
        and  at  the  third  position  the  ATLAS-file  name  used  for G, see
        Section 5.6,
  
  ringinfo
        a list of triples, each containing at the first position the name of a
        file  with  the  matrix  generators,  at  the second position a string
        describing  the ring generated by the matrix entries, and at the third
        position  this  ring  itself;  DisplayAtlasInfo  (2.5-1) displays this
        information  for example for representations over proper extensions of
        the  rational  number field only if the representation is mentioned in
        the ringinfo list,
  
  private
        a  list  of pairs of strings used for administrating private data (see
        Chapter 3);        the        value        is        changed        by
        AtlasOfGroupRepresentationsNotifyPrivateDirectory      (3.1-1)     and
        AtlasOfGroupRepresentationsForgetPrivateDirectory (3.1-2),
  
  TableOfContents
        a  record  with  at  most the components local, remote, types, and the
        names  of private data directories. The values of the components local
        and remote can be computed automatically by ReloadAtlasTableOfContents
        (1.6-1), the value of the component types is set in AGRDeclareDataType
        (5.5-1),  and  the values of the components for local data directories
        are   created   by   AtlasOfGroupRepresentationsNotifyPrivateDirectory
        (3.1-1).
  
  
  5.2 How to Customize the Access to Data files
  
  We discuss the three steps listed in Section 1.7-6.
  
  For  creating  an overview of the locally available data, the first of these
  steps  must  be  available  independent  of  actually  accessing the file in
  question.  For updating the local copy of the server data, the second of the
  above  steps  must be available independent of the third one. Therefore, the
  package  provides  the possibility to extend the default behaviour by adding
  new      records      to      the      accessFunctions      component     of
  AtlasOfGroupRepresentationsInfo  (5.1-5),  the  components  of  which are as
  follows.
  
  
  location( filename, groupname, dirname,
               type )
  
        Let  filename  be  the default filename (without path) of the required
        file,  or a list of such filenames. Let groupname be the ATLAS name of
        the  group  to  which  the  data in these files belong, dirname be the
        default  directory  name  (one of "datagens", "dataword", or the dirid
        value         of         a        private        directory,        see
        AtlasOfGroupRepresentationsNotifyPrivateDirectory  (3.1-1)),  and type
        be  the data type (see AGRDeclareDataType (5.5-1)). This function must
        return  either the absolute path(s) where the mechanism implemented by
        the  current record expects the local version of the given file(s), or
        fail  if this function does not feel responsible for these file(s). In
        the  latter  case, the location function in another record will know a
        path.
  
        The  file(s) is/are regarded as not locally available if all installed
        location  functions  return either fail or paths of nonexisting files,
        in the sense of IsExistingFile (Reference: IsExistingFile).
  
  
  fetch( filepath, filename, groupname,
            dirname, type )
  
        This  function  is  called when a file is not locally available and if
        the  location  function in the current record has returned a path or a
        list  of paths. The arguments dirname and type must be the same as for
        the  location function, and filepath and filename must be strings (not
        lists of strings).
  
        The  return  value  must be true if the function succeeded with making
        the  file  locally available (including postprocessing if applicable),
        and false otherwise.
  
  contents( filepath, type )
        This  function  is  called  when  the location function in the current
        record  has  returned  the  path(s)  filepath, and if either these are
        paths  of  existing  files or the fetch function in the current record
        has  been  called  for these paths, and the return value was true. The
        argument  type  must  be  the  same  as for the location and the fetch
        functions.
  
        The  return  value  must  be the contents of the file(s), in the sense
        that  the  GAP  matrix, matrix list, permutation, permutation list, or
        program  described by the file(s) is returned. This means that besides
        reading  the file(s) via the appropriate function, it may be necessary
        to interpret the contents.
  
  description
        This  must  be  a short string that describes for which kinds of files
        the  functions  in the current record are intended, which file formats
        are     supported     etc.     The     value     is     shown     when
        AtlasOfGroupRepresentationsShowUserParameters (1.7-8) is called.
  
  active
        The  current  accessFunctions  record  is  ignored  by AGRFileContents
        (5.6-2) if the value is not true.
  
  In  AGRFileContents (5.6-2), the records in the accessFunctions component of
  AtlasOfGroupRepresentationsInfo (5.1-5) are considered in reversed order.
  
  By default, the accessFunctions list contains three records. Only for one of
  them,  the active component has the value true. One of the other two records
  can  be  used  to  change  the  access to permutation representations and to
  matrix representations over finite fields such that MeatAxe binary files are
  transferred  and read instead of MeatAxe text files. The fourth record makes
  sense  only  if a local server is accessible, i. e., if the server files can
  be read directly, without being transferred into the data directories of the
  package.
  
  
  5.3 Reading and Writing MeatAxe Format Files
  
  5.3-1 ScanMeatAxeFile
  
  > ScanMeatAxeFile( filename[, q][, "string"] ) _____________________function
  Returns:  the  matrix  or list of permutations stored in the file or encoded
            by the string.
  
  Let  filename be the name of a GAP readable file (see 'Reference: Filename')
  that contains a matrix or a permutation or a list of permutations in MeatAxe
  text  format  (see  the  section  about  the  program  zcv  in  the  MeatAxe
  manual [Rin98]),  and  let  q  be a prime power. ScanMeatAxeFile returns the
  corresponding GAP matrix or list of permutations, respectively.
  
  If the file contains a matrix then the way how it is read by ScanMeatAxeFile
  depends  on  the  value of the global variable CMeatAxe.FastRead (5.1-4). If
  the  parameter  q  is  given  then the result matrix is represented over the
  field  with  q  elements,  the default for q is the field size stored in the
  file.
  
  If  the file contains a list of permutations then it is read with StringFile
  (GAPDoc: StringFile); the parameter q, if given, is ignored in this case.
  
  If  the  string  "string"  is  entered  as the third argument then the first
  argument  must  be  a  string  as obtained by reading a file in MeatAxe text
  format as a text stream (see InputTextFile (Reference: InputTextFile)). Also
  in  this  case, ScanMeatAxeFile returns the corresponding GAP matrix or list
  of permutations, respectively.
  
  5.3-2 MeatAxeString
  
  > MeatAxeString( mat, q ) _________________________________________operation
  > MeatAxeString( perms, degree ) __________________________________operation
  > MeatAxeString( perm, q, dims ) __________________________________operation
  Returns:  a  string  encoding  the  GAP  objects  given  as input in MeatAxe
            format.
  
  In  the  first  form, for a matrix mat whose entries lie in the finite field
  with q elements, MeatAxeString returns a string that encodes mat as a matrix
  over GF(q), in MeatAxe text format.
  
  In the second form, for a nonempty list perms of permutations that move only
  points  up  to  the  positive integer degree, MeatAxeString returns a string
  that  encodes perms as permutations of degree degree, in MeatAxe text format
  (see [Rin98]).
  
  In the third form, for a permutation perm with largest moved point n, say, a
  prime  power q, and a list dims of length 2 containing two positive integers
  larger  than or equal to n, MeatAxeString returns a string that encodes perm
  as  a  matrix over GF(q), of dimensions dims, whose first n rows and columns
  describe  the  permutation  matrix  corresponding to perm, and the remaining
  rows and columns are zero.
  
  When  strings  are  printed  to  files using PrintTo (Reference: PrintTo) or
  AppendTo  (Reference: AppendTo) then line breaks are inserted whenever lines
  exceed  the  number  of  characters  given  by  the second entry of the list
  returned  by  SizeScreen (Reference: SizeScreen), see 'Reference: Operations
  for  Output  Streams'.  This  behaviour  is  not desirable for creating data
  files. So the recommended functions for printing the result of MeatAxeString
  to  a  file  are  FileString  (GAPDoc:  FileString) and WriteAll (Reference:
  WriteAll).
  
  ---------------------------  Example  ----------------------------
    gap> mat:= [ [ 1, -1 ], [ 0, 1 ] ] * Z(3)^0;;
    gap> str:= MeatAxeString( mat, 3 );
    "1 3 2 2\n12\n01\n"
    gap> mat = ScanMeatAxeFile( str, "string" );
    true
    gap> str:= MeatAxeString( mat, 9 );
    "1 9 2 2\n12\n01\n"
    gap> mat = ScanMeatAxeFile( str, "string" );
    true
    gap> perms:= [ (1,2,3)(5,6) ];;
    gap> str:= MeatAxeString( perms, 6 );
    "12 1 6 1\n2\n3\n1\n4\n6\n5\n"
    gap> perms = ScanMeatAxeFile( str, "string" );
    true
    gap> str:= MeatAxeString( perms, 8 );
    "12 1 8 1\n2\n3\n1\n4\n6\n5\n7\n8\n"
    gap> perms = ScanMeatAxeFile( str, "string" );
    true
    gap> perm:= (1,2,4);;
    gap> str:= MeatAxeString( perm, 3, [ 5, 6 ] );
    "2 3 5 6\n2\n4\n3\n1\n5\n"
    gap> mat:= ScanMeatAxeFile( str, "string" );;  Print( mat, "\n" );
    [ [ 0*Z(3), Z(3)^0, 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3) ], 
      [ 0*Z(3), 0*Z(3), 0*Z(3), Z(3)^0, 0*Z(3), 0*Z(3) ], 
      [ 0*Z(3), 0*Z(3), Z(3)^0, 0*Z(3), 0*Z(3), 0*Z(3) ], 
      [ Z(3)^0, 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3) ], 
      [ 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3), Z(3)^0, 0*Z(3) ] ]
    gap> MeatAxeString( mat, 3 ) = str;
    true
  ------------------------------------------------------------------
  
  5.3-3 FFList
  
  > FFList( F ) ______________________________________________________function
  Returns:  a list of elements in the given finite field.
  
  > FFLists____________________________________________________global variable
  
  FFList  is a utility program for the conversion of vectors and matrices from
  MeatAxe  format  to GAP format and vice versa. It is used by ScanMeatAxeFile
  (5.3-1) and MeatAxeString (5.3-2).
  
  For  a  finite  field  F,  FFList returns a list l giving the correspondence
  between the MeatAxe numbering and the GAP numbering of the elements in F.
  
  The  element  of  F  corresponding  to MeatAxe number n is l[ n+1 ], and the
  MeatAxe number of the field element z is Position( l, z ) - 1.
  
  The global variable FFLists is used to store the information about F once it
  has been computed.
  
  ---------------------------  Example  ----------------------------
    gap> FFList( GF(4) );
    [ 0*Z(2), Z(2)^0, Z(2^2), Z(2^2)^2 ]
    gap> IsBound( FFLists[4] );
    true
  ------------------------------------------------------------------
  
  5.3-4 CMtxBinaryFFMatOrPerm
  
  > CMtxBinaryFFMatOrPerm( elm, def, outfile ) _______________________function
  
  Let  the  pair  (elm,  def) be either of the form (M, q) where M is a matrix
  over  a  finite field F, say, with q <= 256 elements, or of the form (pi, n)
  where pi is a permutation with largest moved point at most n. Let outfile be
  a  string.  CMtxBinaryFFMatOrPerm  writes  the C-MeatAxe binary format of M,
  viewed  as  a matrix over F, or of pi, viewed as a permutation on the points
  up to n, to the file with name outfile.
  
  (The binary format is described in the C-MeatAxe manual [Rin98].)
  
  ---------------------------  Example  ----------------------------
    gap> tmpdir:= DirectoryTemporary();;
    gap> mat:= Filename( tmpdir, "mat" );;
    gap> q:= 4;;
    gap> mats:= GeneratorsOfGroup( GL(10,q) );;
    gap> CMtxBinaryFFMatOrPerm( mats[1], q, Concatenation( mat, "1" ) );
    gap> CMtxBinaryFFMatOrPerm( mats[2], q, Concatenation( mat, "2" ) );
    gap> prm:= Filename( tmpdir, "prm" );;
    gap> n:= 200;;
    gap> perms:= GeneratorsOfGroup( SymmetricGroup( n ) );;
    gap> CMtxBinaryFFMatOrPerm( perms[1], n, Concatenation( prm, "1" ) );
    gap> CMtxBinaryFFMatOrPerm( perms[2], n, Concatenation( prm, "2" ) );
  ------------------------------------------------------------------
  
  5.3-5 FFMatOrPermCMtxBinary
  
  > FFMatOrPermCMtxBinary( fname ) ___________________________________function
  Returns:  the matrix or permutation stored in the file.
  
  Let fname be the name of a file that contains the C-MeatAxe binary format of
  a  matrix  over  a  finite  field  or  of  a  permutation,  as  is described
  in [Rin98].  FFMatOrPermCMtxBinary  returns  the corresponding GAP matrix or
  permutation.
  
  ---------------------------  Example  ----------------------------
    gap> FFMatOrPermCMtxBinary( Concatenation( mat, "1" ) ) = mats[1];
    true
    gap> FFMatOrPermCMtxBinary( Concatenation( mat, "2" ) ) = mats[2];
    true
    gap> FFMatOrPermCMtxBinary( Concatenation( prm, "1" ) ) = perms[1];
    true
    gap> FFMatOrPermCMtxBinary( Concatenation( prm, "2" ) ) = perms[2];
    true
  ------------------------------------------------------------------
  
  
  5.4 Reading and Writing ATLAS Straight Line Programs
  
  5.4-1 ScanStraightLineProgram
  
  > ScanStraightLineProgram( filename[, "string"] ) __________________function
  Returns:  a record containing the straight line program.
  
  Let  filename be the name of a file that contains a straight line program in
  the sense that it consists only of lines in the following form.
  
  #anything
        lines starting with a hash sign # are ignored,
  
  echo anything
        lines  starting with echo are ignored for the program component of the
        result  record  (see  below),  they  are  used to set up the bijection
        between  the  labels  used in the program and conjugacy class names in
        the case that the program computes dedicated class representatives,
  
  inp n
        means  that  there are n inputs, referred to via the labels 1, 2, ...,
        n,
  
  inp k a1 a2 ... ak
        means  that  the  next k inputs are referred to via the labels a1, a2,
        ..., ak,
  
  cjr a b
        means that a is replaced by b^(-1) * a * b,
  
  cj a b c
        means that c is defined as b^(-1) * a * b,
  
  com a b c
        means that c is defined as a^(-1) * b^(-1) * a * b,
  
  iv a b
        means that b is defined as a^(-1),
  
  mu a b c
        means that c is defined as a * b,
  
  pwr a b c
        means that c is defined as b^a,
  
  cp a b
        means that b is defined as a copy of a,
  
  oup l
        means that there are l outputs, stored in the labels 1, 2, ..., l, and
  
  oup l b1 b2 ... bl
        means that the next l outputs are stored in the labels b1, b2, ... bl.
  
  Each  of  the  labels  a,  b,  c  can be any nonempty sequence of digits and
  alphabet  characters,  except  that the first argument of pwr must denote an
  integer.
  
  If  the  inp  or  oup  statements  are  missing  then  the  input or output,
  respectively,  is  assumed  to  be given by the labels 1 and 2. There can be
  multiple inp lines at the beginning of the program and multiple oup lines at
  the end of the program. Only the first inp or oup line may omit the names of
  the  elements. For example, an empty file filename or an empty string string
  represent  a  straight  line  program  with  two inputs that are returned as
  outputs.
  
  No  command except cjr may overwrite its own input. For example, the line mu
  a b a is not legal. (This is not checked.)
  
  ScanStraightLineProgram  returns  a  record  containing  as the value of its
  component    program   the   corresponding   GAP   straight   line   program
  (see IsStraightLineProgram  (Reference: IsStraightLineProgram)) if the input
  string  satisfies the syntax rules stated above, and returns fail otherwise.
  In  the  latter  case,  information  about  the  first corrupted line of the
  program is printed if the info level of InfoCMeatAxe (5.1-2) is at least 1.
  
  If  the  string  "string"  is  entered as the second argument then the first
  argument  must  be  a  string  as obtained by reading a file in MeatAxe text
  format as a text stream (see InputTextFile (Reference: InputTextFile)). Also
  in  this  case,  ScanStraightLineProgram  returns  either  a record with the
  corresponding GAP straight line program or fail.
  
  If  the  input describes a straight line program that computes certain class
  representatives  of  the  group  in  question  then  the  result record also
  contains the component outputs. Its value is a list of strings, the entry at
  position  i  denoting  the  name  of  the class in which the i output of the
  straight  line program lies; see Section 2.4 for the definition of the class
  names that occur.
  
  Such   straight   line   programs   must  end  with  a  sequence  of  output
  specifications of the following form.
  
  ---------------------------  Example  ----------------------------
    echo "Classes 1A 2A 3A 5A 5B"
    oup 5 3 1 2 4 5
  ------------------------------------------------------------------
  
  This example means that the list of outputs of the program contains elements
  of  the  classes 1A, 2A, 3A, 5A, and 5B (in this order), and that inside the
  program, these elements are referred to by the names 3, 1, 2, 4, and 5.
  
  5.4-2 AtlasStringOfProgram
  
  > AtlasStringOfProgram( prog[, outputnames] ) ______________________function
  > AtlasStringOfProgram( prog[, "mtx"] ) ____________________________function
  Returns:  a string encoding the straight line program/decision in the format
            used in ATLAS files.
  
  For   a   straight   line   program   or   straight   line   decision   prog
  (see IsStraightLineProgram     (Reference:     IsStraightLineProgram)    and
  IsStraightLineDecision  (4.1-1)),  this function returns a string describing
  the  input  format  of  an equivalent straight line program or straight line
  decision  as  used in the ATLAS of Group Representations, that is, the lines
  are of the form described in ScanStraightLineProgram (5.4-1).
  
  A  list of strings that is given as the optional second argument outputnames
  is  interpreted  as  the  class  names  corresponding  to  the outputs; this
  argument  has  the  effect  that  appropriate  echo statements appear in the
  result string.
  
  If  the string "mtx" is given as the second argument then the result has the
  format  used in the C-MeatAxe (see [Rin98]) rather than the format described
  in  Section 5.4.  (Note that the C-MeatAxe format does not make sense if the
  argument outputnames is given, and that this format does not support inp and
  oup statements.)
  
  The  argument  prog  must  not  be  a  black  box program (see IsBBoxProgram
  (4.2-1)).
  
  ---------------------------  Example  ----------------------------
    gap> str:= "inp 2\nmu 1 2 3\nmu 3 1 2\niv 2 1\noup 2 1 2";;
    gap> prg:= ScanStraightLineProgram( str, "string" );
    rec( program := <straight line program> )
    gap> prg:= prg.program;;
    gap> Display( prg );
    # input:
    r:= [ g1, g2 ];
    # program:
    r[3]:= r[1]*r[2];
    r[2]:= r[3]*r[1];
    r[1]:= r[2]^-1;
    # return values:
    [ r[1], r[2] ]
    gap> StringOfResultOfStraightLineProgram( prg, [ "a", "b" ] );
    "[ (aba)^-1, aba ]"
    gap> AtlasStringOfProgram( prg );
    "inp 2\nmu 1 2 3\nmu 3 1 2\niv 2 1\noup 2\n"
    gap> prg:= StraightLineProgram( "(a^2b^3)^-1", [ "a", "b" ] );
    <straight line program>
    gap> Print( AtlasStringOfProgram( prg ) );
    inp 2
    pwr 2 1 4
    pwr 3 2 5
    mu 4 5 3
    iv 3 4
    oup 1 4
    gap> prg:= StraightLineProgram( [ [2,3], [ [3,1,1,4], [1,2,3,1] ] ], 2 );
    <straight line program>
    gap> Print( AtlasStringOfProgram( prg ) );
    inp 2
    pwr 3 2 3
    pwr 4 1 5
    mu 3 5 4
    pwr 2 1 6
    mu 6 3 5
    oup 2 4 5
    gap> Print( AtlasStringOfProgram( prg, "mtx" ) );
    # inputs are expected in 1 2
    zsm pwr3 2 3
    zsm pwr4 1 5
    zmu 3 5 4
    zsm pwr2 1 6
    zmu 6 3 5
    echo "outputs are in 4 5"
    gap> str:= "inp 2\nchor 1 2\nchor 2 3\nmu 1 2 3\nchor 3 5";;
    gap> prg:= ScanStraightLineDecision( str );;
    gap> AtlasStringOfProgram( prg.program );
    "inp 2\nchor 1 2\nchor 2 3\nmu 1 2 3\nchor 3 5\n"
  ------------------------------------------------------------------
  
  
  5.5 Data Types Used in the ATLAS of Group Representations
  
  Each representation or program that is administrated by the AtlasRep package
  belongs  to  a  unique  data  type.  Informally,  examples of data types are
  "permutation  representation", "matrix representation over the integers", or
  "straight line program for computing class representatives".
  
  The idea is that for each data type, there can be
  
  --    a column of its own in the output produced by DisplayAtlasInfo (2.5-1)
        when  called  without  arguments or with only argument a list of group
        names,
  
  --    a  line  format of its own for the output produced by DisplayAtlasInfo
        (2.5-1) when called with first argument a group name,
  
  --    an input format of its own for AtlasProgram (2.5-3),
  
  --    an input format of its own for OneAtlasGeneratingSetInfo (2.5-4), and
  
  --    specific  tests  for  the  data of this data type; these functions are
        used by the global tests described in Section 5.8.
  
  Formally,  a  data  type is defined by a record whose components are used by
  the interface functions. The details are described in the following.
  
  5.5-1 AGRDeclareDataType
  
  > AGRDeclareDataType( kind, name, record ) _________________________function
  
  Let  kind  be  one  of  the  strings "rep" or "prg", and record be a record.
  AGRDeclareDataType  declares  a new data type of representations (if kind is
  "rep")  or  of  programs  (if  kind  is  "prg").  For each group used in the
  AtlasRep  package,  the  record that contains the information about the data
  will  have  a component name whose value is a list containing the data about
  the new type. Examples of name are "perm", "matff", and "classes".
  
  Mandatory components of record are
  
  FilenameFormat
        This  defines  the format of the filenames containing data of the type
        in  question.  The value must be a list that can be used as the second
        argument  of  AGRParseFilenameFormat (5.6-1), such that only filenames
        of  the  type  in  question  match.  (It  is  not checked whether this
        "detection  function"  matches  exactly  one type, so one must be very
        careful here when declaring a new type.)
  
  AddFileInfo
        This  defines  the information stored in the table of contents for the
        data  of  the  type.  The  value  must  be a function that takes three
        arguments  (the current list of data for the type and the given group,
        a  list returned by AGRParseFilenameFormat (5.6-1) for the given type,
        and  a  filename).  This function adds the necessary parts of the data
        entry  to  the list, and returns true if the data belongs to the type,
        otherwise  false  is returned; note that the latter case occurs if the
        filename  matches  the format description but additional conditions on
        the parts of the name are not satisfied (for example integer parts may
        be required to be positive or prime powers).
  
  ReadAndInterpretDefault
        This is the function that does the work for the default contents value
        of  the  accessFunctions  component of AtlasOfGroupRepresentationsInfo
        (5.1-5),  see  Section 5.2.  This function must take a path and return
        the GAP object given by this file.
  
  AddDescribingComponents (for rep only)
        This  function takes two arguments, a record (that will be returned by
        AtlasGenerators   (2.5-2),   OneAtlasGeneratingSetInfo   (2.5-4),   or
        AllAtlasGeneratingSetInfos  (2.5-5))  and  the  type record record. It
        sets  the components p, dim, id, and ring that are promised for return
        values of the abovementioned three functions.
  
  DisplayGroup (for rep only)
        This  defines  the  format  of  the  lines printed by DisplayAtlasInfo
        (2.5-1)  for  a given group. The value must be a function that takes a
        list  as  returned by the function given in the component AddFileInfo,
        and  returns  the  string  to  be  printed  for  the representation in
        question.
  
  Optional components of record are
  
  DisplayOverviewInfo
        This   is   used   to   introduce  a  new  column  in  the  output  of
        DisplayAtlasInfo (2.5-1) when this is called without arguments or with
        a  list  of group names as its only argument. The value must be a list
        of length three, containing at its first position a string used as the
        header of the column, at its second position one of the strings "r" or
        "l",  denoting  right or left aligned column entries, and at its third
        position  a  function  that  takes  two arguments (a list of tables of
        contents of the AtlasRep package and a group name), and returns a list
        of length two, containing the string to be printed as the column value
        and  true  or  false, depending on whether private data is involved or
        not. (The default is to print no column for the data type.)
  
  DisplayPRG (for prg only)
        This is used in DisplayAtlasInfo (2.5-1) for ATLAS programs. The value
        must  be  a  function  that  takes four arguments (a list of tables of
        contents  to  examine, the name of the given group, a list of integers
        or  true for the required standardization, and a list of all available
        standardizations),  and  returns  the  list  of  lines (strings) to be
        printed as the information about the available programs of the current
        type  and  for  the  given  group.  (The default is to return an empty
        list.)
  
  AccessGroupCondition (for rep only)
        This is used in DisplayAtlasInfo (2.5-1) and OneAtlasGeneratingSetInfo
        (2.5-4). The value must be a function that takes two arguments (a list
        as   returned   by  AGRParseFilenameFormat  (5.6-1),  and  a  list  of
        conditions), and returns true or false, depending on whether the first
        argument  satisfies  the conditions. (The default value is ReturnFalse
        (Reference: ReturnFalse).)
  
        The function must support conditions such as [ IsPermGroup, true ] and
        [  NrMovedPoints,  [ 5, 6 ] ], in general a list of functions followed
        by  a  prescribed  value, a list of prescribed values, another (unary)
        function,  or the string "minimal". For an overview of the interesting
        functions, see DisplayAtlasInfo (2.5-1).
  
  AccessPRG (for prg only)
        This  is  used  in  AtlasProgram (2.5-3). The value must be a function
        that  takes three arguments (the record with the information about the
        given  group in the current table of contents, an integer or a list of
        integers  or  true  for  the  required  standardization, and a list of
        conditions  given  by the optional arguments of AtlasProgram (2.5-3)),
        and  returns  either  fail or a list that together with the group name
        forms  the  identifier  of a program that matches the conditions. (The
        default value is ReturnFail (Reference: ReturnFail).)
  
  AtlasProgram (for prg only)
        This  is  used in AtlasProgram (2.5-3) to create the result value from
        the identifier. (The default value is AtlasProgramDefault, which works
        whenever  the  second entry of the identifier is the filename; this is
        not  the case for example if the program is the composition of several
        programs.)
  
  TOCEntryString
        This is used in StoreAtlasTableOfContents (1.6-2). The value must be a
        function  that  takes  two  arguments (the name name of the type and a
        list  as  returned  by  AGRParseFilenameFormat  (5.6-1)  and returns a
        string  that  describes  the  appropriate  function call. (The default
        value is TOCEntryStringDefault.)
  
  PostprocessFileInfo
        This  is  used  in  the  construction  of  a  table  of  contents  via
        ReloadAtlasTableOfContents  (1.6-1),  for  testing  or rearranging the
        data  of  the  current table of contents. The value must be a function
        that  takes two arguments, the table of contents record and the record
        in  it  that  belongs  to  one fixed group. (The default function does
        nothing.)
  
  SortTOCEntries
        This  is  used  in  the  construction  of  a  table  of  contents (see
        ReloadAtlasTableOfContents  (1.6-1)),  for  sorting  the entries after
        they   have   been   added  and  after  the  value  of  the  component
        PostprocessFileInfo has been called. The value must be a function that
        takes  a  list  as  returned  by  AGRParseFilenameFormat  (5.6-1), and
        returns  the sorting key. (There is no default value, which means that
        no sorting is needed.)
  
  TestFileHeaders (for rep only)
        This          is          used         in         the         function
        AtlasOfGroupRepresentationsTestFileHeaders  (5.8-5). The value must be
        a  function  that  takes  the  same  four arguments as AGRFileContents
        (5.6-2),  except that the first argument "datagens" can be replaced by
        "local"  and  that  the  third  argument  is  a  list  as  returned by
        AGRParseFilenameFormat  (5.6-1).  (The  default  value  is  ReturnTrue
        (Reference: ReturnTrue).)
  
  TestFiles (for rep only)
        This  is  used  in  the  function AtlasOfGroupRepresentationsTestFiles
        (5.8-7).  The  format of the value and the default are the same as for
        the value of the component TestFileHeaders.
  
  TestWords (for prg only)
        This  is  used  in  the  function AtlasOfGroupRepresentationsTestWords
        (5.8-6).  The value must be a function that takes five arguments where
        the  first four are the same arguments as for AGRFileContents (5.6-2),
        except  that the first argument "dataword" can be replaced by "local",
        and  the  fifth  argument is true or false, indicating verbose mode or
        not.
  
  
  5.6 Filenames Used in the ATLAS of Group Representations
  
  The  data of each local GAP version of the ATLAS of Group Representations is
  either  private (see Chapter 3) or is stored in the two directories datagens
  and  dataword.  In the following, we describe the format of filenames in the
  latter two directories, as a reference of the "official" part of the ATLAS.
  
  In  the directory datagens, the generators for the representations available
  are  stored,  the  directory  dataword  contains  the  programs  to  compute
  conjugacy  class representatives, generators of maximal subgroups, images of
  generators  under  automorphisms of a given group G from standard generators
  of G, and to check and compute standard generators (see Section 2.3).
  
  The  name  of each data file in the ATLAS of Group Representations describes
  the  contents  of  the  file.  This  section  lists  the  definitions of the
  filenames used.
  
  Each  filename consists of two parts, separated by a minus sign -. The first
  part is always of the form groupnameGi, where the integer i denotes the i-th
  set  of  standard  generators  for  the  group  G, say, with ATLAS-file name
  groupname  (see 2.2).  The translations of the name groupname to the name(s)
  used    within    GAP    is    given    by   the   component   GAPnames   of
  AtlasOfGroupRepresentationsInfo (5.1-5).
  
  The  filenames in the directory dataword have one of the following forms. In
  each of these cases, the suffix Wn means that n is the version number of the
  program.
  
  groupnameGi-cycWn
        In this case, the file contains a straight line program that returns a
        list of representatives of generators of maximally cyclic subgroups of
        G. An example is Co1G1-cycW1.
  
  groupnameGi-cclsWn
        In this case, the file contains a straight line program that returns a
        list   of   conjugacy  class  representatives  of  G.  An  example  is
        RuG1-cclsW1.
  
  groupnameGicycWn-cclsWm
        In this case, the file contains a straight line program that takes the
        return value of the program in the file groupnameGi-cycWn (see above),
        and returns a list of conjugacy class representatives of G. An example
        is M11G1cycW1-cclsW1.
  
  groupnameGi-maxkWn
        In  this  case,  the  file contains a straight line program that takes
        generators  of  G  w.r.t. the  i-th  set  of  standard generators, and
        returns  a list of generators (in general not standard generators) for
        a  subgroup  U in the k-th class of maximal subgroups of G. An example
        is J1G1-max7W1.
  
  groupnameGimaxkWn-subgroupnameGjWm
        In this case, the file contains a straight line program that takes the
        return  value  of  the  program  in  the  file groupnameGi-maxkWn (see
        above),  which  are  generators  for a group U, say; subgroupname is a
        name  for U, and the return value is a list of standard generators for
        U, w.r.t. the j-th set of standard generators. (Of course this implies
        that  the  groups  in  the  k-th  class  of maximal subgroups of G are
        isomorphic  to  the  group  with  name  subgroupname.)  An  example is
        J1G1max1W1-L211G1W1; the first class of maximal subgroups of the Janko
        group  J_1  consists of groups isomorphic to the linear group L_2(11),
        for which standard generators are defined.
  
  groupnameGi-aoutnameWn
        In  this  case,  the  file contains a straight line program that takes
        generators  of  G  w.r.t. the  i-th  set  of  standard generators, and
        returns the list of their images under the outer automorphism alpha of
        G  given  by the name outname; if this name is empty then alpha is the
        unique nontrivial outer automorphism of G; if it is a positive integer
        k  then  alpha is a generator of the unique cyclic order k subgroup of
        the outer automorphism group of G; if it is of the form 2_1 or 2a, 4_2
        or  4b,  3_3  or  3c  ...  then  alpha  generates  the cyclic group of
        automorphisms  induced on G by G.2_1, G.4_2, G.3_3 ...; finally, if it
        is  of  the  form  kpd, with k one of the above forms and d an integer
        then  d  denotes  the  number  of  dashes appended to the automorphism
        described by k; if d = 1 then d can be omitted. Examples are A5G1-aW1,
        L34G1-a2_1W1,  U43G1-a2_3pW1,  and  O8p3G1-a2_2p5W1;  these file names
        describe  the outer order 2 automorphism of A_5 (induced by the action
        of  S_5) and the order 2 automorphisms of L_3(4), U_4(3), and O_8^+(3)
        induced    by   the   actions   of   L_3(4).2_1,   U_4(3).2_2^',   and
        O_8^+(3).2_2^{'''''}, respectively.
  
  groupnameGi-GjWn
        In  this  case,  the  file contains a straight line program that takes
        generators  of  G  w.r.t. the  i-th  set  of  standard generators, and
        returns  standard  generators  of  G  w.r.t. the  j-th set of standard
        generators. An example is L35G1-G2W1.
  
  groupnameGi-checkn
        In  this  case,  the file contains a straight line decision that takes
        generators  of  G,  and  returns true if these generators are standard
        generators w.r.t. the i-th standardization, and false otherwise.
  
  groupnameGi-Pn
        In  this  case,  the file contains a straight line decision that takes
        some  group  elements, and returns true if these elements are standard
        generators   for   G,   w.r.t. the  i-th  standardization,  and  false
        otherwise.
  
  groupnameGi-findn
        In  this  case,  the  file  contains  a black box program that takes a
        group,  and returns (if it is successful) a set of standard generators
        for G, w.r.t. the i-th standardization.
  
  groupnameGi-XdescrWn
        In  this  case,  the  file contains a straight line program that takes
        generators  of G w.r.t. the i-th set of standard generators, and whose
        return value corresponds to descr. This format is used only in private
        extensions  (see  Chapter 3), such a script can be accessed with descr
        as the third argument of AtlasProgram (2.5-3).
  
  The  filenames in the directory datagens have one of the following forms. In
  each  of  these  cases,  id  is a (possibly empty) string that starts with a
  lowercase      alphabet     letter     (see IsLowerAlphaChar     (Reference:
  IsLowerAlphaChar)),  and  m  is  a  nonnegative  integer,  meaning  that the
  generators  are written w.r.t. the m-th basis (the meaning is defined by the
  ATLAS developers).
  
  groupnameGi-fqrdimidBm.mnr
        a file in MeatAxe text file format containing the nr-th generator of a
        matrix  representation  over  the  field with q elements, of dimension
        dim. An example is S5G1-f2r4aB0.m1.
  
  groupnameGi-pnidBm.mnr
        a file in MeatAxe text file format containing the nr-th generator of a
        permutation representation on n points. An example is M11G1-p11B0.m1.
  
  groupnameGi-ArdimidBm.g
        a   GAP   readable   file   containing  all  generators  of  a  matrix
        representation  of  dimension  dim  over an algebraic number field not
        specified further. An example is A5G1-Ar3aB0.g.
  
  groupnameGi-ZrdimidBm.g
        a   GAP   readable   file   containing  all  generators  of  a  matrix
        representation  over  the  integers,  of  dimension dim. An example is
        A5G1-Zr4B0.g.
  
  groupnameGi-HrdimidBm.g
        a   GAP   readable   file   containing  all  generators  of  a  matrix
        representation  over  a  quaternion  algebra  over an algebraic number
        field, of dimension dim. An example is 2A6G1-Hr2aB0.g.
  
  groupnameGi-ZnrdimidBm.g
        a   GAP   readable   file   containing  all  generators  of  a  matrix
        representation  of  dimension  dim over the ring of integers mod n. An
        example is 2A8G1-Z4r4aB0.g.
  
  5.6-1 AGRParseFilenameFormat
  
  > AGRParseFilenameFormat( string, format ) _________________________function
  Returns:  a  list of strings and integers if string matches format, and fail
            otherwise.
  
  Let  string  be a filename, and format be a list [ [ c_1, c_2, ..., c_n ], [
  f_1,  f_2, ..., f_n ] ] such that each entry c_i is a list of strings and of
  functions  that take a character as their argument and return true or false,
  and  such  that each entry f_i is a function for parsing a filename, such as
  the currently undocumented functions ParseForwards and ParseBackwards.
  
  AGRParseFilenameFormat  returns a list of strings and integers such that the
  concatenation  of  their  String (Reference: String) values yields string if
  string  matches  format, and fail otherwise. Matching is defined as follows.
  Splitting  string  at each minus character (-) yields m parts s_1, s_2, ...,
  s_m.  The string string matches format if s_i matches the conditions in c_i,
  for  1  <=  i  <=  n, in the sense that applying f_i to s_i and c_i yields a
  non-fail result.
  
  ---------------------------  Example  ----------------------------
    gap> format:= [ [ [ IsChar, "G", IsDigitChar ],
    >                 [ "p", IsDigitChar, IsLowerAlphaOrDigitChar,
    >                   "B", IsDigitChar, ".m", IsDigitChar ] ],
    >               [ ParseBackwards, ParseForwards ] ];;
    gap> AGRParseFilenameFormat( "A6G1-p10B0.m1", format );
    [ "A6", "G", 1, "p", 10, "", "B", 0, ".m", 1 ]
    gap> AGRParseFilenameFormat( "A6G1-p15aB0.m1", format );
    [ "A6", "G", 1, "p", 15, "a", "B", 0, ".m", 1 ]
    gap> AGRParseFilenameFormat( "A6G1-f2r16B0.m1", format );
    fail
  ------------------------------------------------------------------
  
  5.6-2 AGRFileContents
  
  > AGRFileContents( dirname, groupname, filename, type ) ____________function
  Returns:  the  GAP object obtained from reading and interpreting the file(s)
            with name(s) filename.
  
  Let  dirname  and  groupname  be  strings, filename be a string or a list of
  strings,  and  type be a data type (see AGRDeclareDataType (5.5-1)). dirname
  must  be  one  of  "datagens",  "dataword",  or the dirid value of a private
  directory, see AtlasOfGroupRepresentationsNotifyPrivateDirectory (3.1-1). If
  groupname  is  the  ATLAS-file  name  of a group G (see Section 2.2), and if
  filename  is  either the name of an accessible file in the dirname directory
  of  the  ATLAS,  or a list of such filenames, with data concerning G and for
  the  data  type  type,  then  AGRFileContents  returns  the  contents of the
  corresponding  file(s),  in  the sense that the file(s) (or equivalent ones,
  see  Section 1.7-6) is/are read, and the result is interpreted if necessary;
  otherwise fail is returned.
  
  Note  that  if  filename  refers  to  file(s)  already stored in the dirname
  directory  then AGRFileContents does not check whether the table of contents
  of the ATLAS of Group Representations actually contains filename.
  
  
  5.7 The Tables of Contents of the ATLAS of Group Representations
  
  The  list  of  data  currently  available  is  stored  in  several tables of
  contents,  one  for  the local GAP data, one for the data on remote servers,
  and  one  for  each  private  data  directory.  These tables of contents are
  created by ReloadAtlasTableOfContents (1.6-1).
  
  It  is  assumed  that the local data directories contain only files that are
  also   available  on  servers.  Private  extensions  to  the  database  (cf.
  Section 1.8  and Chapter 3) cannot be handled by putting the data files into
  the local directories.
  
  Each  table  of contents is represented by a record whose components are the
  ATLAS-file  names  of the groups (see Section 2.2) and lastupdated, a string
  describing  the date of the last update of this table of contents. The value
  for each group name is a record whose components are the names of those data
  types (see Section 5.5) for which data are available.
  
  Note  that  the  name  mapping  between  the ATLAS-file and GAP names of the
  groups     is     provided     by     the     groupnames     component    of
  AtlasOfGroupRepresentationsInfo  (5.1-5),  and  information  about  the base
  rings of matrix representations is provided by the ringinfo component. Group
  names  are  notified  with AGRGNAN (5.7-1), and base ring information can be
  notified  with  AGRRNG  (5.7-2); these two administrational functions may be
  useful for private extensions of the package (see Chapter 3).
  
  5.7-1 AGRGNAN
  
  > AGRGNAN( gapname, atlasname[, size[, maxessize[, "all"[, compatinfo]]]] ) function
  
  Let gapname be a string denoting a GAP group name, and atlasname be a string
  denoting the corresponding ATLAS-file name used in filenames of the ATLAS of
  Group Representations. The following optional arguments are supported.
  
  size
        the order of the corresponding group,
  
  maxessizes
        a  (not  necessarily dense) list of orders of the maximal subgroups of
        this group
  
  complete
        the string "all" if the maxessizes list is complete,
  
  compatinfo
        a list of entries of the form [ std, factname, factstd, flag ] meaning
        that  mapping standard generators of standardization std to the factor
        group  with  GAP  group  name  factname,  via the natural epimorphism,
        yields standard generators of standardization factstd if flag is true.
  
  AGRGNAN  adds  the  list of its arguments to the list stored in the GAPnames
  component  of AtlasOfGroupRepresentationsInfo (5.1-5), making the ATLAS data
  involving atlasname accessible for the group with name gapname.
  
  An  example  of  a  valid  call  is  AGRGNAN("A6.2_2","PGL29",360), see also
  Section 3.3.
  
  5.7-2 AGRRNG
  
  > AGRRNG( filename, descr ) ________________________________________function
  
  Let  filename  be  a  string  denoting  the  name  of  a file containing the
  generators  of a matrix representation over a ring that is not determined by
  the  filename, and let descr be a string describing this ring R, say. AGRRNG
  adds  the  triple  [ filename, descr, R ] to the list stored in the ringinfo
  component of AtlasOfGroupRepresentationsInfo (5.1-5).
  
  An example of a valid call is AGRRNG("A5G1-Ar3aB0","Field([Sqrt(5)])").
  
  
  5.8 Sanity Checks for the ATLAS of Group Representations
  
  The  fact  that  the  ATLAS  of Group Representations is designed as an open
  database   (see   Section 1.7-1)  makes  it  especially  desirable  to  have
  consistency  checks  available  which  can be run automatically whenever new
  data  are  added  by the developers of the ATLAS. The tests described in the
  following  can  also  be  used  for  private  extensions of the package (see
  Chapter 3).
  
  The   file  tst/testall.g  of  the  package  contains  ReadTest  (Reference:
  ReadTest)  statements  for executing a collection of such sanity checks; one
  can  run  them  by starting GAP in the tst directory, and then calling Read(
  "testall.g" ). If no problem occurs then GAP prints only lines starting with
  one of the following.
  
  ---------------------------  Example  ----------------------------
    + $Id:
    + GAP4stones:
  ------------------------------------------------------------------
  
  The required space and time for running these tests depends on the amount of
  locally available data.
  
  The  examples  in this manual form a part of these tests, they are collected
  in the file tst/docxpl.tst of the package.
  
  The    file    tst/atlasrep.tst    contains    calls    to   the   functions
  AtlasOfGroupRepresentationsTestGroupOrders   (5.8-1),   which   checks   the
  consistency   of   the   stored   group   orders   and   the   actual  data,
  AtlasOfGroupRepresentationsTestFileHeaders   (5.8-5),   which   checks   the
  consistency  of  the  names of MeatAxe text files and the first lines of the
  files,   and   AtlasOfGroupRepresentationsTestWords  (5.8-6),  which  checks
  whether the available programs do what they promise.
  
  The      calls      to     AtlasOfGroupRepresentationsTestFiles     (5.8-7),
  AtlasOfGroupRepresentationsTestClassScripts           (5.8-8),           and
  AGR_TestMinimalDegrees  (4.3-5)  are  not  part of the tests that are run by
  reading tst/testall.g.
  
  All these tests apply only to the local table of contents (see Section 5.7),
  that  is,  only  those data files are checked that are actually available in
  the  local  GAP installation. No files are fetched from servers during these
  tests.
  
  Further tests, such as the consistency of different versions of server data,
  exist but are not part of the distributed package.
  
  5.8-1 AtlasOfGroupRepresentationsTestGroupOrders
  
  > AtlasOfGroupRepresentationsTestGroupOrders(  ) ___________________function
  Returns:  false if a contradiction was found, true otherwise.
  
  This  function  checks  whether  the  group  orders  stored  in the GAPnames
  component  of  AtlasOfGroupRepresentationsInfo  (5.1-5)  coincide  with  the
  orders  computed  from  an  ATLAS permutation representation of degree up to
  10^4, from the character table or the table of marks with the given name, or
  from  the  inner structure of the name (supported is a splitting of the name
  at  the first dot (.), where the two parts of the name are examined with the
  same criteria in order to derive the group order).
  
  A  message  is printed for each group name for which no order is stored (and
  perhaps  now  can  be  stored),  for  which the stored group order cannot be
  verified, for which a contradiction was found.
  
  5.8-2 AtlasOfGroupRepresentationsTestSubgroupOrders
  
  > AtlasOfGroupRepresentationsTestSubgroupOrders(  ) ________________function
  Returns:  false if a contradiction was found, true otherwise.
  
  This  function  checks whether the orders of maximal subgroups stored in the
  GAPnames  component of AtlasOfGroupRepresentationsInfo (5.1-5) coincide with
  the orders computed from an ATLAS permutation representation of degree up to
  10^4, from the character table or the table of marks with the given name, or
  from  the  information  about  maximal  subgroups of a factor group modulo a
  central subgroup that is contained in the derived subgroup.
  
  A  message  is printed for each group name for which no order is stored (and
  perhaps  now  can  be  stored),  for  which the stored group order cannot be
  verified, for which a contradiction was found.
  
  5.8-3 AtlasOfGroupRepresentationsTestStdCompatibility
  
  > AtlasOfGroupRepresentationsTestStdCompatibility(  ) ______________function
  Returns:  false if a contradiction was found, true otherwise.
  
  This  function  checks whether the compatibility info stored in the GAPnames
  component  of AtlasOfGroupRepresentationsInfo (5.1-5) coincide with computed
  values.
  
  The  following  criterion is used for computing the value for a group G. Use
  the  GAP Character Table Library to determine factor groups F of G for which
  standard  generators  are  defined  and  moreover a presentation in terms of
  these   standard   generators   is  known.  Evaluate  the  relators  of  the
  presentation  in  the  standard  generators  of  G,  and let N be the normal
  closure of these elements in G. Then mapping the standard generators of F to
  the  Ncosets  of  the standard generators of G is an epimorphism. If |G/N| =
  |F|  holds  then  G/N and F are isomorphic, and the standard generators of G
  and  F are compatible in the sense that mapping the standard generators of G
  to their N-cosets yields standard generators of F.
  
  A message is printed for each group name for which no compatibility info was
  stored  and now can be stored, for which the stored info cannot be verified,
  for which a contradiction was found.
  
  5.8-4 AtlasOfGroupRepresentationsTestCompatibleMaxes
  
  > AtlasOfGroupRepresentationsTestCompatibleMaxes(  ) _______________function
  Returns:  false if a contradiction was found, true otherwise.
  
  This  function checks whether the information about maximal subgroups stored
  in the maxext components of the records stored in the TableOfContents.remote
  component  of AtlasOfGroupRepresentationsInfo (5.1-5) coincide with computed
  values.
  
  The  following criterion is used for computing the value for a group G. If F
  is  a  factor  group  of  G such that the standard generators of G and F are
  compatible (see AtlasOfGroupRepresentationsTestStdCompatibility (5.8-3)) and
  if there are a presentation for F and a permutation representation of G then
  it  is checked whether the "maxes" type scripts for F can be used to compute
  also  generators  for the maximal subgroups of G; if not then words in terms
  of  the standard generators are computed such that the results of the script
  for  F  together  with  the images of these words describe the corresponding
  maximal subgroup of G.
  
  A message is printed for each group name for which no compatibility info was
  stored  and now can be stored, for which the stored info cannot be verified,
  for which a contradiction was found.
  
  5.8-5 AtlasOfGroupRepresentationsTestFileHeaders
  
  > AtlasOfGroupRepresentationsTestFileHeaders( [tocid[, groupname]] ) function
  Returns:  false if an error occurs, otherwise true.
  
  First  suppose  that  this  function is called with two arguments tocid, the
  identifier  of a directory (see Section sect:Adding a Private Data Directory
  (3.1)), and groupname, an ATLAS-file name that occurs as a component name in
  the  table  of contents of the directory. The function checks for those data
  files  for  groupname in the tocid directory that are in MeatAxe text format
  whether  the filename and the header line are consistent; it checks the data
  file  in GAP format whether the file name is consistent with the contents of
  the file.
  
  If  only  one argument tocid is given then all representations available for
  groupname are checked with the three argument version.
  
  If  only  one  argument  tocid  is  given  then  all available groups in the
  directory  with  identifier  tocid  are  checked;  the contents of the local
  dataword  directory  can  be  checked by entering "local", which is also the
  default for tocid.
  
  5.8-6 AtlasOfGroupRepresentationsTestWords
  
  > AtlasOfGroupRepresentationsTestWords( [tocid[, groupname]] ) _____function
  Returns:  false if an error occurs, otherwise true.
  
  Called       with       one       argument       tocid,       a      string,
  AtlasOfGroupRepresentationsTestWords  processes all programs that are stored
  in  the  directory  with identifier tocid (see Section sect:Adding a Private
  Data  Directory (3.1)), using the function stored in the TestWords component
  of  the  data type in question. The contents of the local dataword directory
  can be checked by entering "local", which is also the default.
  
  If  the string groupname, an ATLAS-file name that occurs as a component name
  in  the  table of contents of the directory, is given as the second argument
  then only the data files for this group are tested.
  
  5.8-7 AtlasOfGroupRepresentationsTestFiles
  
  > AtlasOfGroupRepresentationsTestFiles( [tocid[, groupname]] ) _____function
  Returns:  false if an error occurs, otherwise true.
  
  This  function  is an analogue of AtlasOfGroupRepresentationsTestFileHeaders
  (5.8-5).  It  checks whether reading MeatAxe text files with ScanMeatAxeFile
  (5.3-1)  returns  non-fail results. It does not check whether the first line
  of a MeatAxe text file is consistent with the filename, since this is tested
  by AtlasOfGroupRepresentationsTestFileHeaders (5.8-5).
  
  5.8-8 AtlasOfGroupRepresentationsTestClassScripts
  
  > AtlasOfGroupRepresentationsTestClassScripts( [groupname] ) _______function
  Returns:  false if an error occurs, otherwise true.
  
  First  suppose  that  AtlasOfGroupRepresentationsTestClassScripts  is called
  with    one    argument    groupname,   the   name   of   a   component   in
  AtlasOfGroupRepresentationsInfo.TableOfContents.(  "local"  ).  If  the  GAP
  table   library   contains  an  ordinary  character  table  with  Identifier
  (Reference:   Identifier!for   character   tables)   value   the   GAP  name
  corresponding  to  groupname  then  it is checked whether all those straight
  line   programs  for  this  group  that  return  class  representatives  are
  consistent  with  the character table in the sense that the class names used
  occur  for the table, and that the element orders and centralizer orders for
  the classes are correct.
  
  If  no  argument is given then all available groups are checked with the one
  argument version.