chap7.txt

  
  7 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 3).
  
  Besides   global   variables   used   for   administrational  purposes  (see
  Section 7.1)  and  several  sanity  checks  (see  Section 7.8),  they can be
  regarded  as  the interface between the data actually contained in the files
  and  the corresponding GAP objects (see Section 7.2, 7.3, 7.4, and 7.5), and
  the  interface between the remote and the local version of the database (see
  Section 7.6  and 7.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 [Rin]). 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.
  
  
  7.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  (7.1-1),  InfoCMeatAxe  (7.1-2),  and  InfoBBox
  (7.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
  (7.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).
  
  7.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.
  
  7.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.
  
  7.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 6.2) is
  printed. The default level is 0, no information is printed on this level.
  
  7.1-4 CMeatAxe.FastRead
  
  CMeatAxe.FastRead global variable
  
  If  this  component  is  bound  and  has the value true then ScanMeatAxeFile
  (7.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.
  
  7.1-5 AGR
  
  AGR global variable
  
  is  a  record  whose  components are functions and data that are used by the
  higher level interface functions.
  
  7.1-6 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 4.3) 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 4.3-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
        controls  whether  the  GAP package IO [Neu14] or the external program
        wget is used to fetch data files, see 4.3-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 4.3-4,
  
  displayFunction
        the function that is used by DisplayAtlasInfo (3.5-1) for printing the
        formatted data, see Section 4.3-5,
  
  accessFunctions
        a  list  of records, each describing how to access the data files, see
        Sections 4.3-6 and 7.2, and
  
  markprivate
        a  string  used  in DisplayAtlasInfo (3.5-1) to mark private data, see
        Section  5.2.
  
  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 3.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 7.6,
  
  private
        a  list  of pairs of strings used for administrating private data (see
        Chapter 5);        the        value        is        changed        by
        AtlasOfGroupRepresentationsNotifyPrivateDirectory      (5.1-1)     and
        AtlasOfGroupRepresentationsForgetPrivateDirectory (5.1-2),
  
  characterinfo, permrepinfo, ringinfo
        additional   information   about   representations,   concerning   the
        characters    afforded,   the   point   stabilizers   of   permutation
        representations, and the ring of definition of matrix representations;
        this information is used by DisplayAtlasInfo (3.5-1),
  
  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
        (4.2-1),    the   value   of   the   component   types   is   set   in
        AGR.DeclareDataType  (7.5-1),  and  the  values  of the components for
        local        data        directories        are       created       by
        AtlasOfGroupRepresentationsNotifyPrivateDirectory (5.1-1).
  
  
  7.2 How to Customize the Access to Data files
  
  We discuss the three steps listed in Section 4.3-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 (7.1-6). Its components 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  (5.1-1)),  and type
        be the data type (see AGR.DeclareDataType (7.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, interpreting the
        contents may be necessary.
  
  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     used     by
        AtlasOfGroupRepresentationsUserParameters (4.3-8).
  
  active
        The  current  accessFunctions  record  is  ignored by AGR.FileContents
        (7.6-2) if the value is not true.
  
  In AGR.FileContents (7.6-2), the records in the accessFunctions component of
  AtlasOfGroupRepresentationsInfo (7.1-6) 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.
  
  
  7.3 Reading and Writing MeatAxe Format Files
  
  7.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 C-MeatAxe
  documentation [Rin]),  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 (7.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.
  
  7.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 C-MeatAxe text
  format (see [Rin]).
  
  In the third form, for a permutation perm with largest moved point n, say, a
  prime  power  q,  and  a  list  dims  of  length two 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
  
  
  Note  that  the  output of MeatAxeString in the case of permutation matrices
  depends on the user preference WriteMeatAxeFilesOfMode2.
  
    Example  
    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> pref:= UserPreference( "AtlasRep", "WriteMeatAxeFilesOfMode2" );;
    gap> SetUserPreference( "AtlasRep", "WriteMeatAxeFilesOfMode2", true );
    gap> MeatAxeString( mat, 3 ) = str;
    true
    gap> SetUserPreference( "AtlasRep", "WriteMeatAxeFilesOfMode2", false );
    gap> MeatAxeString( mat, 3 );
    "1 3 5 6\n010000\n000100\n001000\n100000\n000010\n"
    gap> SetUserPreference( "AtlasRep", "WriteMeatAxeFilesOfMode2", pref );
  
  
  7.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
  (7.3-1) and MeatAxeString (7.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
  
  
  7.3-4 CMtxBinaryFFMatOrPerm
  
  CMtxBinaryFFMatOrPerm( elm, def, outfile[, base] )  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 (π, n)
  where  π 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 π, viewed as a permutation on the points up
  to n, to the file with name outfile.
  
  In  the  case  of  a  permutation  π,  the optional argument base prescribes
  whether  the  binary  file  contains  the  points from 0 to deg- 1 (base= 0,
  supported  by  version 2.4  of  the  C-MeatAxe)  or the points from 1 to deg
  (base=  1,  supported  by  older versions of the C-MeatAxe). The default for
  base  is given by the value of the user preference BaseOfMeatAxePermutation,
  see Section 4.3-11.
  
  (The binary format is described in the C-MeatAxe manual [Rin].)
  
    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" ) );
    gap> CMtxBinaryFFMatOrPerm( perms[1], n, Concatenation( prm, "1a" ), 0 );
    gap> CMtxBinaryFFMatOrPerm( perms[2], n, Concatenation( prm, "2b" ), 1 );
  
  
  7.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 [Rin].
  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
    gap> FFMatOrPermCMtxBinary( Concatenation( prm, "1a" ) ) = perms[1];
    true
    gap> FFMatOrPermCMtxBinary( Concatenation( prm, "2b" ) ) = perms[2];
    true
  
  
  
  7.4 Reading and Writing ATLAS Straight Line Programs
  
  7.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 (7.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 3.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 five names 3, 1, 2, 4, and 5.
  
  7.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  (6.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 (7.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 [Rin]) rather than the format described in
  Section 7.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
  (6.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"
  
  
  
  7.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 (3.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
        (3.5-1) when called with first argument a group name,
  
      an input format of its own for AtlasProgram (3.5-3),
  
      an input format of its own for OneAtlasGeneratingSetInfo (3.5-5), and
  
      specific  tests  for  the  data of this data type; these functions are
        used by the global tests described in Section 7.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.
  
  7.5-1 AGR.DeclareDataType
  
  AGR.DeclareDataType( kind, name, record )  function
  
  Let  kind  be  one  of  the  strings "rep" or "prg", and record be a record.
  AGR.DeclareDataType  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 AGR.ParseFilenameFormat (7.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 declaring a new type
        needs care.)
  
  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 AGR.ParseFilenameFormat (7.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
        (7.1-6),  see  Section 7.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   (3.5-2),   OneAtlasGeneratingSetInfo   (3.5-5),   or
        AllAtlasGeneratingSetInfos  (3.5-6))  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
        (3.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 (3.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  fail,  indicating that no new column shall be
        printed.)
  
  DisplayPRG (for prg only)
        This is used in DisplayAtlasInfo (3.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 (3.5-1) and OneAtlasGeneratingSetInfo
        (3.5-5). The value must be a function that takes two arguments (a list
        as  returned  by  OneAtlasGeneratingSetInfo  (3.5-5),  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 (3.5-1).
  
  AccessPRG (for prg only)
        This  is  used  in  AtlasProgram (3.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 (3.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 (3.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.)
  
  AtlasProgramInfo (for prg only)
        This  is  used  in AtlasProgramInfo (3.5-4) to create the result value
        from the identifier. (The default value is AtlasProgramDefault.)
  
  TOCEntryString
        This is used in StoreAtlasTableOfContents (4.2-2). The value must be a
        function  that  takes  two  arguments (the name name of the type and a
        list  as  returned  by  AGR.ParseFilenameFormat  (7.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  (4.2-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  (4.2-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  AGR.ParseFilenameFormat (7.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 AGR.Test.FileHeaders. The value must be a
        function  that  takes  the  same  four  arguments  as AGR.FileContents
        (7.6-2),  except that the first argument "datagens" can be replaced by
        "local"  and  that  the  third  argument  is  a  list  as  returned by
        AGR.ParseFilenameFormat  (7.6-1).  (The  default  value  is ReturnTrue
        (Reference: ReturnTrue).)
  
  TestFiles (for rep only)
        This  is  used in the function AGR.Test.Files. 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  AGR.Test.Words. The value must be a
        function  that  takes five arguments where the first four are the same
        arguments  as  for  AGR.FileContents  (7.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.
  
  
  7.6 Filenames Used in the ATLAS of Group Representations
  
  The data of each local GAP version of the ATLAS of Group Representations are
  either private (see Chapter 5) or are 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 3.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 3.2).  The translations of the name groupname to the name(s)
  used    within    GAP    is    given    by   the   component   GAPnames   of
  AtlasOfGroupRepresentationsInfo (7.1-6).
  
  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 α of G
        given  by the name outname; if this name is empty then α is the unique
        nontrivial outer automorphism of G; if it is a positive integer k then
        α  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  α  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 5), such a script can be accessed with descr
        as the third argument of AtlasProgram (3.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.
  
  7.6-1 AGR.ParseFilenameFormat
  
  AGR.ParseFilenameFormat( 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.
  
  AGR.ParseFilenameFormat 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, AGR.IsLowerAlphaOrDigitChar,
    >                   "B", IsDigitChar, ".m", IsDigitChar ] ],
    >               [ ParseBackwards, ParseForwards ] ];;
    gap> AGR.ParseFilenameFormat( "A6G1-p10B0.m1", format );
    [ "A6", "G", 1, "p", 10, "", "B", 0, ".m", 1 ]
    gap> AGR.ParseFilenameFormat( "A6G1-p15aB0.m1", format );
    [ "A6", "G", 1, "p", 15, "a", "B", 0, ".m", 1 ]
    gap> AGR.ParseFilenameFormat( "A6G1-f2r16B0.m1", format );
    fail
  
  
  7.6-2 AGR.FileContents
  
  AGR.FileContents( 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 AGR.DeclareDataType (7.5-1)). dirname
  must  be  one  of  "datagens",  "dataword",  or the dirid value of a private
  directory, see AtlasOfGroupRepresentationsNotifyPrivateDirectory (5.1-1). If
  groupname  is  the  ATLAS-file  name  of a group G (see Section 3.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  AGR.FileContents  returns  the contents of the
  corresponding  file(s),  in  the sense that the file(s) (or equivalent ones,
  see  Section 4.3-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 AGR.FileContents does not check whether the table of contents
  of the ATLAS of Group Representations actually contains filename.
  
  
  7.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 (4.2-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 4.5  and Chapter 5) 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 3.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 7.5) for which data are available.
  
  Here are the administrational functions that are used to build the tables of
  contents.  Some  of  them  may  be useful also for private extensions of the
  package (see Chapter 5).
  
  The  following  functions define group names, available representations, and
  straight line programs.
  
  AGR.GNAN( gapname, atlasname )
        Called  with  two  strings  gapname  (the  GAP  name of the group) and
        atlasname   (the  ATLAS  name  of  the  group),  AGR.GNAN  stores  the
        information   in  the  list  AtlasOfGroupRepresentationsInfo.GAPnames,
        which  defines  the name mapping between the ATLAS names and GAP names
        of the groups.
  
        This function may be used also for private extensions of the database.
  
        An example of a valid call is AGR.GNAN("A5.2","S5").
  
  AGR.GRP( dirname, simpname, groupname)
        Called  with  three strings, AGR.GRP stores in the groupname component
        of  AtlasOfGroupRepresentationsInfo  (7.1-6)  in  which  path  on  the
        servers  the  data  about  the  group with ATLAS name groupname can be
        found.
  
        This function is not intended for private extensions of the database.
  
        An example of a valid call is AGR.GRP("alt","A5","S5").
  
  AGR.TOC( typename, filename, crcfile )
        Called  with  two  strings  typename  and  filename, and a list crc of
        integers,  AGR.TOC  notifies  an  entry  to the TableOfContents.remote
        component  of  AtlasOfGroupRepresentationsInfo (7.1-6), where typename
        must be the name of the data type to which the entry belongs, filename
        must  be  the  prefix of the data file(s), and crc must be the list of
        CrcFile (Reference: CrcFile) values of the file(s).
  
        This function is not intended for private extensions of the database.
  
        An        example        of        a        valid        call       is
        AGR.TOC("perm","S5G1-p5B0.m",[-3581724,115937465]).
  
  The  following  functions  add  data  about  the  groups  and their standard
  generators.  The  function  calls  must  be executed after the corresponding
  AGR.GNAN calls.
  
  AGR.GRS( gapname, size )
        Called  with  the  string  gapname (the GAP name of the group) and the
        integer size (the order of the group), AGR.GRS stores this information
        in AtlasOfGroupRepresentationsInfo.GAPnames.
  
        An example of a valid call is AGR.GRS("A5.2",120).
  
  AGR.MXN( gapname, nrMaxes )
        Called  with  the  string  gapname (the GAP name of the group) and the
        integer  nrMaxes  (the  number  of classes of maximal subgroups of the
        group),       AGR.MXN       stores       the       information      in
        AtlasOfGroupRepresentationsInfo.GAPnames.
  
        An example of a valid call is AGR.MXN("A5.2",4).
  
  AGR.MXO( gapname, sizesMaxes )
        Called  with  the  string  gapname (the GAP name of the group) and the
        list  sizesMaxes  (of  subgroup  orders  of  the  classes  of  maximal
        subgroups  of  the  group,  not  necessarily  dense, in non-increasing
        order),       AGR.MXO       stores       the       information      in
        AtlasOfGroupRepresentationsInfo.GAPnames.
  
        An example of a valid call is AGR.MXO("A5.2",[60,24,20,12]).
  
  AGR.MXS( gapname, structureMaxes )
        Called  with  the  string  gapname (the GAP name of the group) and the
        list  structureMaxes  (of  strings  describing  the  structures of the
        maximal subgroups of the group, not necessarily dense), AGR.MXS stores
        the information in AtlasOfGroupRepresentationsInfo.GAPnames.
  
        An        example        of        a        valid        call       is
        AGR.MXS("A5.2",["A5","S4","5:4","S3x2"]).
  
  AGR.KERPRG( gapname, kernelProgram )
        Called  with  the  string  gapname (the GAP name of the group) and the
        list kernelProgram (with entries the standardization of the group, the
        GAP  name  of a factor group, and the list of lines of a straight line
        program that computes generators of the kernel of the epimorphism from
        the  group  to the factor group), AGR.KERPRG stores the information in
        AtlasOfGroupRepresentationsInfo.GAPnames.
  
        An example of a valid call is AGR.KERPRG("2.J2",[1,"J2",[[[1,2]]]]).
  
  AGR.STDCOMP
        Called  with  the  string  gapname (the GAP name of the group) and the
        list  factorCompatibility  (with  entries  the  standardization of the
        group,  the  GAP  name  of a factor group, the standardization of this
        factor  group,  and  true  or  false,  indicating  whether mapping the
        standard  generators  for  gapname  to those of factgapname defines an
        epimorphism),     AGR.STDCOMP     stores     the     information    in
        AtlasOfGroupRepresentationsInfo.GAPnames.
  
        An example of a valid call is AGR.STDCOMP("2.A5.2",[1,"A5.2",1,true]).
  
  The  following  functions  add  data  about representations or straight line
  programs  that  are already known. The function calls must be executed after
  the corresponding AGR.TOC calls.
  
  AGR.RNG( repname, descr )
        Called  with  two  strings  repname  (denoting  the  name  of  a  file
        containing  the generators of a matrix representation over a ring that
        is  not determined by the filename) and descr (describing this ring R,
        say), AGR.RNG adds the triple [ repname, descr, R ] to the list stored
        in the ringinfo component of AtlasOfGroupRepresentationsInfo (7.1-6).
  
        An        example        of        a        valid        call       is
        AGR.RNG("A5G1-Ar3aB0","Field([Sqrt(5)])").
  
  AGR.TOCEXT( atlasname, std, maxnr, files )
        Called  with  the  string atlasname (the ATLAS name of the group), the
        positive  integers  std (the standardization) and maxnr (the number of
        the  class  of maximal subgroups), and the list files (of filenames of
        straight  line  programs  for  computing  generators  of  the maxnr-th
        maximal  subgroup,  using  a  straight line program for a factor group
        plus   perhaps   some  straight  line  program  for  computing  kernel
        generators), AGR.TOCEXT stores the information in the maxext component
        of the atlasname component of the "remote" table of contents.
  
        An example of a valid call is AGR.TOCEXT("2A5",1,3,["A5G1-max3W1"]).
  
  AGR.API( repname, info )
        Called  with  the  string  repname (denoting the name of a permutation
        representation)  and the list info (describing the point stabilizer of
        this  representation),  AGR.API  binds  the  component  repname of the
        record AtlasOfGroupRepresentationsInfo.permrepinfo to info.
  
        info has the following entries.
  
            At position 1, the transitivity is stored.
  
            If the transitivity is zero then the second entry is the list of
              orbit lengths.
  
            If  the  transitivity  is  positive then the second entry is the
              rank of the action.
  
            If  the  transitivity is positive then the third entry is one of
              the strings "prim", "imprim", denoting primitivity or not.
  
            If  the  transitivity  is  positive  then  the fourth entry is a
              string  describing the structure of the point stabilizer. If the
              third  entry  is  "imprim"  then  this description consists of a
              subgroup part and a maximal subgroup part, separated by " < ".
  
            If  the  third  entry  is  "prim" then the fifth entry is either
              "???" or it denotes the number of the class of maximal subgroups
              that are the point stabilizers.
  
        An        example        of        a        valid        call       is
        AGR.API("A5G1-p5B0",[3,2,"prim","A4",1]).
  
  AGR.CHAR( groupname, repname, char, pos[, charname] )
        Called  with  the  strings  groupname  (the GAP name of the group) and
        repname  (denoting  the  name of the representation), the integer char
        (the  characteristic  of the representation), and pos (the position or
        list  of positions of the irreducible constituent(s)), AGR.CHAR stores
        the  information  in  AtlasOfGroupRepresentationsInfo.characterinfo. A
        string describing the character can be entered as charname.
  
        An        example        of        a        valid        call       is
        AGR.CHAR("M11","M11G1-p11B0",0,[1,2],"1a+10a").
  
  These  functions  are  used  to create the initial table of contents for the
  server  data  of  the  AtlasRep  package when the file gap/atlasprm.g of the
  package is read.
  
  
  7.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 4.3-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
  Section  7.8-1  can  be  used  also  for data from private extensions of the
  package  (see  Chapter 5),  Section 7.8-2 lists tests which do not have this
  property.
  
  All  these tests apply only to the local table of contents (see Section 7.7)
  or  to  private  extensions.  So  only those data files are checked that are
  actually  available in the local GAP installation. No files are fetched from
  servers  during  these  tests. The required space and time for running these
  tests depend on the amount of locally available data.
  
  The  file  tst/testall.g  of  the  package  contains  Test (Reference: Test)
  statements  for  executing  a  collection of such sanity checks; one can run
  them  by  calling  ReadPackage( "AtlasRep", "tst/testall.g" ). If no problem
  occurs then GAP prints only lines starting with one of the following.
  
    Example  
    + Input file:
    + GAP4stones:
  
  
  Some  of  the checks compute and verify additional data, such as information
  about  point  stabilizers  of  permutation  representations. In these cases,
  output   lines   starting   with   #E  are  error  messages  that  point  to
  inconsistencies,  whereas  output  lines  starting with #I inform about data
  that  have  been computed and were not yet stored, or about stored data that
  were not verified.
  
  The  examples  in  the  package  manual  form  a part of the tests, they are
  collected in the file tst/docxpl.tst of the package.
  
  
  7.8-1 Sanity Checks for a Table of Contents
  
  The  following  tests  can  be used to check the data that belong to a given
  table  of contents. Each of these tests is given by a function with optional
  argument  tocid,  the identifying string that had been entered as the second
  argument  of  AtlasOfGroupRepresentationsNotifyPrivateDirectory (5.1-1). The
  contents of the local dataword directory can be checked by entering "local",
  which  is also the default for tocid. The function returns false if an error
  occurs,  otherwise  true.  Currently  the  following  tests of this kind are
  available.
  
  AGR.Test.Words( [tocid] )
        processes  all straight line programs that are stored in the directory
        with  identifier  tocid,  using  the  function stored in the TestWords
        component of the data type in question.
  
  AGR.Test.FileHeaders( [tocid] )
        checks  whether  all  MeatAxe  text format data files in the directory
        with  identifier  tocid have a header line that is consistent with the
        filename,  and  whether  the  contents of all GAP format data files in
        this directory is consistent with the contents of the file.
  
  AGR.Test.Files( [tocid] )
        checks whether the MeatAxe text files that are stored in the directory
        with  identifier  tocid  can be read with ScanMeatAxeFile (7.3-1) such
        that  the  result is not fail. The function does not check whether the
        first  line  of  a  MeatAxe text file is consistent with the filename,
        since this can be tested with AGR.Test.FileHeaders.
  
  AGR.Test.BinaryFormat( [tocid] )
        checks  whether  all  MeatAxe  text format data files in the directory
        with     identifier     tocid     satisfy    that    applying    first
        CMtxBinaryFFMatOrPerm  (7.3-4)  and then FFMatOrPermCMtxBinary (7.3-5)
        yields the same object.
  
  AGR.Test.Primitivity( [tocid] )
        checks   the   stored  primitivity  information  for  the  permutation
        representations  that  are  stored  in  the  directory with identifier
        tocid.
  
  AGR.Test.Characters( [tocid] )
        checks the stored character information for the matrix and permutation
        representations  that  are  stored  in  the  directory with identifier
        tocid.
  
  
  7.8-2 Other Sanity Checks
  
  The  tests described in this section are not intended for checking data from
  private  extensions of the AtlasRep package. Each of the tests is given by a
  function  without  arguments that returns false if a contradiction was found
  during  the  test,  and  true  otherwise. Additionally, certain messages are
  printed when contradictions between stored and computed data are found, when
  stored  data  cannot  be  verified computationally, or when the computations
  yield improvements of the stored data. Currently the following tests of this
  kind are available.
  
  AGR.Test.GroupOrders()
        checks  whether  the  group orders stored in the GAPnames component of
        AtlasOfGroupRepresentationsInfo (7.1-6) coincide with the group orders
        computed  from  an  ATLAS  permutation  representation of degree up to
        AGR.Test.MaxTestDegree, from the character table or the table of marks
        with the given name, or from the 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.
  
  AGR.Test.MaxesOrders()
        checks whether the orders of maximal subgroups stored in the component
        GAPnames  of AtlasOfGroupRepresentationsInfo (7.1-6) coincide with the
        orders   computed   from  the  restriction  of  an  ATLAS  permutation
        representation  of  degree  up  to  AGR.Test.MaxTestDegree,  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
        normal subgroup that is contained in the Frattini subgroup.
  
  AGR.Test.MaxesStructure()
        checks  whether the names of maximal subgroups stored in the component
        GAPnames  of AtlasOfGroupRepresentationsInfo (7.1-6) coincide with the
        names computed from the GAP character table with the given name.
  
  AGR.Test.StdCompatibility()
        checks  whether  the  information  about the compatibility of standard
        generators  of  a  group  and  its factor groups that is stored in the
        GAPnames    component   of   AtlasOfGroupRepresentationsInfo   (7.1-6)
        coincides 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 N-cosets 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.
  
  AGR.Test.CompatibleMaxes()
        checks  whether  the information about deriving straight line programs
        for  restricting  to subgroups from straight line programs that belong
        to a factor group 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 the test function AGR.Test.StdCompatibility) and
        if  there are a presentation for F and a permutation representation of
        G  then  it is checked whether the "maxes" type straight line programs
        for  F  can be used to compute generators for the maximal subgroups of
        G;  if  not  then  generators of the kernel of the natural epimorphism
        from G to F, must be added.
  
  AGR.Test.ClassScripts()
        checks whether the straight line programs that compute representatives
        of certain conjugacy classes are consistent with information stored on
        the  GAP  character  table of the group in question, in the sense that
        the given class names really occur in the character table and that the
        element orders and centralizer orders for the classes are correct.
  
  AGR.Test.CycToCcls()
        checks    whether   some   straight   line   program   that   computes
        representatives  of  conjugacy classes of a group can be computed from
        the  ordinary  GAP  character  table of that group and a straight line
        program  that  computes  representatives  of cyclic subgroups. In this
        case  the  missing  scripts  are  printed if the level of InfoAtlasRep
        (7.1-1) is at least 1.
  
  AGR.Test.Standardization()
        checks  whether  all  generating sets corresponding to the same set of
        standard  generators  have  the same element orders; for the case that
        straight line programs for computing certain class representatives are
        available,  also  the  orders  of  these  representatives  are checked
        w. r. t. all generating sets.
  
  AGR.Test.StdTomLib()
        checks  whether the standard generators are compatible with those that
        occur in the TomLib package.
  
  AGR.Test.KernelGenerators()
        checks  whether  the  information  stored in the GAPnames component of
        AtlasOfGroupRepresentationsInfo  (7.1-6)  about straight line programs
        for  computing  generators  of  the  kernels  of  natural epimorphisms
        between ATLAS groups coincides 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 such that mapping standard
        generators  of G to those of F defines a homomorphism, and such that a
        presentation  of  F  in  terms  of  its  standard generators is known.
        Evaluating the relators of the presentation in the standard generators
        of G yields normal subgroup generators for the kernel.
  
        A  message is printed for each group name for which some straight line
        program  for  computing  kernel  generators was not stored but now was
        computed, or for which the stored info cannot be verified,
  
  AGR.Test.MinimalDegrees()
        checks  that the (permutation and matrix) representations available in
        the ATLAS of Group Representations do not have smaller degree than the
        claimed minimum.