chap5.txt

  
  5 Private Extensions of the AtlasRep Package
  
  It  may  be  interesting  to use the functions of the GAP interface also for
  representations  or  programs  that  are  not  part  of  the  ATLAS of Group
  Representations. This chapter describes how to achieve this.
  
  The  main  idea  is that users can notify directories containing the private
  data files, which may consist of
  
  1   new faithful representations and programs for groups that are declared
        already in the official ATLAS of Group Representations,
  
  2   the  declaration of groups that are not declared in the official ATLAS
        of  Group  Representations, and representations and programs for them,
        and
  
  3   the definition of new kinds of representations and programs.
  
  The first two issues are dealt with in Section 5.1 and Section 5.2. The last
  is described in Section 7.5.
  
  Finally, an example of using private extensions is given in Section 5.3.
  
  Several  of  the sanity checks for the official part of the AtlasRep package
  make   sense   also   for  private  extensions,  see  Section 7.8  for  more
  information.
  
  
  5.1 Adding a Private Data Directory
  
  After the AtlasRep package has been loaded into the GAP session, one can add
  private  data.  However,  one should not add private files to the local data
  directories  of  the package, or modify files in these directories. Instead,
  additional  data should be put into separate directories. It should be noted
  that a data file is fetched from a server only if the local data directories
  do  not  contain  a  file with this name, independent of the contents of the
  files.  (As a consequence, corrupted files in the local data directories are
  not automatically replaced by a correct server file.)
  
  5.1-1 AtlasOfGroupRepresentationsNotifyPrivateDirectory
  
  AtlasOfGroupRepresentationsNotifyPrivateDirectory( dir[, dirid][, test] )  function
  Returns:  true  if  none  of  the  filenames  with  admissible format in the
            directory  dir  is  contained in other data directories and if the
            data  belongs  to groups whose names have been declared, otherwise
            false.
  
  Let  dir  be a directory (see 'Reference: Directories') or a string denoting
  the  name of a directory (such that the GAP object describing this directory
  can  be  obtained  by  calling  Directory  (Reference:  Directory)  with the
  argument  dir).  In the following, let dirname be the name of the directory.
  So  dirname can be an absolute path or a path relative to the home directory
  of  the  user  (starting with a tilde character ~) or a path relative to the
  directory where GAP was started.
  
  If  the  optional  argument  dirid is given, it must be a string. This value
  will  be  used in the identifier components of the records that are returned
  by interface functions (see Section 3.5) for data contained in the directory
  dir. Note that the directory name may be different in different GAP sessions
  or  for  different  users  who  want  to  access  the same data, whereas the
  identifier  components shall be independent of such differences. The default
  for dirid is dirname.
  
  If  the  optional  argument  test is given, it must be true or false. In the
  true  case, consistency checks are switched on while the file toc.g is read.
  This  costs  some  extra time, but it is recommended after each extension of
  the file toc.g. The default for test is false.
  
  AtlasOfGroupRepresentationsNotifyPrivateDirectory  notifies  the data in the
  directory  dir to the AtlasRep package. First the pair [ dirname, dirid ] is
  added  to  the private component of AtlasOfGroupRepresentationsInfo (7.1-6).
  If the directory contains a file with the name toc.g then this file is read;
  this file is useful for adding new group names using AGR.GNAN and for adding
  describing  data  about the representations, see Section 7.7. Next the table
  of  contents  of  the  private  directory  is  built  from the list of files
  contained  in  the  private  directory  or  in its subdirectories (one layer
  deep).
  
  Only  those files are considered whose names match an admissible format (see
  Section 7.6). Filenames that are already contained in another data directory
  of  the AtlasRep package are ignored, and messages about these filenames are
  printed if the info level of InfoAtlasRep (7.1-1) is at least 1.
  
  Note  that  this  implies  that the files of the official (i.e. non-private)
  data directories have priority over files in private directories.
  
  If  the  directory  contains  files  for  groups  whose  names have not been
  declared  before and if the info level of InfoAtlasRep (7.1-1) is at least 1
  then a message about these names is printed.
  
  For  convenience,  the  user  may  collect the notifications of private data
  directories in the file gaprc (see Section 'Reference: The gap.ini and gaprc
  files').
  
  5.1-2 AtlasOfGroupRepresentationsForgetPrivateDirectory
  
  AtlasOfGroupRepresentationsForgetPrivateDirectory( dirid )  function
  
  If  dirid  is  the  identifier  of  a  private  data directory that has been
  notified with AtlasOfGroupRepresentationsNotifyPrivateDirectory (5.1-1) then
  AtlasOfGroupRepresentationsForgetPrivateDirectory removes the directory from
  the  list of notified private directories; this means that from then on, the
  data in this directory cannot be accessed anymore in the current session.
  
  
  5.2 The Effect of Private Extensions on the User Interface
  
  First suppose that only new groups or new data for known groups are added.
  
  In this case, DisplayAtlasInfo (3.5-1) lists the private representations and
  programs in the same way as the official data, except that private parts are
  marked   with   the   string   stored   in   the  component  markprivate  of
  AtlasOfGroupRepresentationsInfo  (7.1-6);  by default, this is a star *. The
  ordering of representations listed by DisplayAtlasInfo (3.5-1) (and referred
  to   by  AtlasGenerators  (3.5-2))  will  in  general  change  when  private
  directories  are  notified. If several private directories are used then the
  ordering  of data may depend on the ordering of notifications. For the other
  interface functions described in Chapter 3, the only difference is that also
  the   private   data   can  be  accessed.  In  particular  the  free  format
  groupnameGi-XdescrWn  for  straight  line  programs (see Section 7.6) may be
  used  in  private  directories;  the  data can be accessed with AtlasProgram
  (3.5-3), where the last two arguments are the strings "other" and descr.
  
  If  also private data types are introduced (see Section 7.5) then additional
  columns  or  rows  can appear in the output of DisplayAtlasInfo (3.5-1), and
  new  inputs  can become meaningful for all interface functions. Examples for
  these changes can be found in Section 5.3.
  
  
  5.3 An Example of Extending the AtlasRep Package
  
  In the beginning we set the info level of InfoAtlasRep (7.1-1) to 1.
  
    Example  
    gap> level:= InfoLevel( InfoAtlasRep );;
    gap> SetInfoLevel( InfoAtlasRep, 1 );
  
  
  Let  us assume that the directory privdir contains data for the cyclic group
  C_4  of order 4 and for the alternating group A_5 on 5 points, respectively.
  Note  that  it  is  obvious  what the term standard generators means for the
  group C_4.
  
  Further let us assume that privdir contains the following files.
  
  C4G1-p4B0.m1
        a faithful permutation representation of C_4 on 4 points,
  
  C4G1-max1W1
        the straight line program that returns the square of its unique input,
  
  C4G1-a2W1
        the  straight  line  program that raises its unique input to the third
        power,
  
  C4G1-XtestW1
        the straight line program that returns the square of its unique input,
  
  A5G1-p60B0.m1 and A5G1-p60B0.m2
        the regular permutation representation of A_5.
  
  The directory and the files can be created as follows.
  
    Example  
    gap> prv:= DirectoryTemporary( "privdir" );;
    gap> FileString( Filename( prv, "C4G1-p4B0.m1" ),
    >                MeatAxeString( [ (1,2,3,4) ], 4 ) );;
    gap> FileString( Filename( prv, "C4G1-max1W1" ),
    >                "inp 1\npwr 2 1 2\noup 1 2\n" );;
    gap> FileString( Filename( prv, "C4G1-XtestW1" ),
    >                "inp 1\npwr 2 1 2\noup 1 2\n" );;
    gap> FileString( Filename( prv, "C4G1-a2W1" ),
    >                "inp 1\npwr 3 1 2\noup 1 2\n" );;
    gap> FileString( Filename( prv, "C4G1-Ar1aB0.g" ),
    >                "return rec( generators:= [ [[E(4)]] ] );\n" );;
    gap> points:= Elements( AlternatingGroup( 5 ) );;
    gap> FileString( Filename( prv, "A5G1-p60B0.m1" ),
    >      MeatAxeString( [ Permutation( (1,2)(3,4), points, OnRight ) ], 60 ) );;
    gap> FileString( Filename( prv, "A5G1-p60B0.m2" ),
    >      MeatAxeString( [ Permutation( (1,3,5), points, OnRight ) ], 60 ) );;
  
  
  (We  could also introduce intermediate directories C4 and A5, say, each with
  the  data  for  one  group  only.  Here we do not show this because creating
  directories  programmatically seems to be possible only with the GAP package
  IO.)
  
  The official part of the AtlasRep package does not contain information about
  C_4,  so  we first notify this group, in the file privdir/toc.g. Besides the
  name  of the group, we store the following information: the group order, the
  number  of  (classes  of) maximal subgroups, their orders, their structures,
  and  describing  data  about the two permutation representations. (The group
  A_5  is  known with name A5 in the official part of the AtlasRep package, so
  it cannot be notified again.)
  
    Example  
    gap> FileString( Filename( prv, "toc.g" ), Concatenation( [
    >        "AGR.GNAN(\"C4\",\"C4\");\n",
    >        "AGR.GRS(\"C4\",4);\n",
    >        "AGR.MXN(\"C4\",1);\n",
    >        "AGR.MXO(\"C4\",[2]);\n",
    >        "AGR.MXS(\"C4\",[\"C2\"]);\n",
    >        "AGR.API(\"C4G1-p4B0\",[1,4,\"imprim\",\"1 < C2\"]);\n",
    >        "AGR.API(\"A5G1-p60B0\",[1,60,\"imprim\",\"1 < A4\"]);\n",
    >        ] ) );;
  
  
  Then we notify the private directory.
  
    Example  
    gap> AtlasOfGroupRepresentationsNotifyPrivateDirectory( prv, "priv", true );
    true
  
  
  Now we can use the interface functions for accessing the data in the private
  directory.
  
    Example  
    gap> DisplayAtlasInfo( [ "C4" ] );
    group | # | maxes | cl | cyc | out | fnd | chk | prs
    ------+---+-------+----+-----+-----+-----+-----+----
    C4*   | 2 |     1 |    |     |   2 |     |     |    
    gap> DisplayAtlasInfo( "C4" );
    Representations for G = C4:    (all refer to std. generators 1)
    ---------------------------
    1: G <= Sym(4)*   rank 4, on cosets of 1 < C2
    2: G <= GL(1a,C)* 
    
    Programs for G = C4:    (all refer to std. generators 1)
    --------------------
    automorphisms:
      2*
    maxes (all 1):
      1*:  C2
    other scripts:
      "test"*
    gap> DisplayAtlasInfo( "C4", IsPermGroup, true );
    Representations for G = C4:    (all refer to std. generators 1)
    ---------------------------
    1: G <= Sym(4)* rank 4, on cosets of 1 < C2
    gap> DisplayAtlasInfo( "C4", IsMatrixGroup );
    Representations for G = C4:    (all refer to std. generators 1)
    ---------------------------
    2: G <= GL(1a,C)* 
    gap> DisplayAtlasInfo( "C4", Dimension, 2 );
    gap> DisplayAtlasInfo( "A5", NrMovedPoints, 60 );
    Representations for G = A5:    (all refer to std. generators 1)
    ---------------------------
    4: G <= Sym(60)* rank 60, on cosets of 1 < A4
    gap> info:= OneAtlasGeneratingSetInfo( "C4" );
    rec( groupname := "C4", id := "", 
      identifier := [ [ "priv", "C4" ], [ "C4G1-p4B0.m1" ], 1, 4 ], 
      isPrimitive := false, p := 4, rankAction := 4, 
      repname := "C4G1-p4B0", repnr := 1, size := 4, 
      stabilizer := "1 < C2", standardization := 1, transitivity := 1, 
      type := "perm" )
    gap> AtlasGenerators( info.identifier );
    rec( generators := [ (1,2,3,4) ], groupname := "C4", id := "", 
      identifier := [ [ "priv", "C4" ], [ "C4G1-p4B0.m1" ], 1, 4 ], 
      isPrimitive := false, p := 4, rankAction := 4, 
      repname := "C4G1-p4B0", repnr := 1, size := 4, 
      stabilizer := "1 < C2", standardization := 1, transitivity := 1, 
      type := "perm" )
    gap> AtlasProgram( "C4", 1 );
    rec( groupname := "C4", 
      identifier := [ [ "priv", "C4" ], "C4G1-max1W1", 1 ], 
      program := <straight line program>, size := 2, standardization := 1,
      subgroupname := "C2" )
    gap> AtlasProgram( "C4", "maxes", 1 );
    rec( groupname := "C4", 
      identifier := [ [ "priv", "C4" ], "C4G1-max1W1", 1 ], 
      program := <straight line program>, size := 2, standardization := 1,
      subgroupname := "C2" )
    gap> AtlasProgram( "C4", "maxes", 2 );
    fail
    gap> AtlasGenerators( "C4", 1 );
    rec( generators := [ (1,2,3,4) ], groupname := "C4", id := "", 
      identifier := [ [ "priv", "C4" ], [ "C4G1-p4B0.m1" ], 1, 4 ], 
      isPrimitive := false, p := 4, rankAction := 4, 
      repname := "C4G1-p4B0", repnr := 1, size := 4, 
      stabilizer := "1 < C2", standardization := 1, transitivity := 1, 
      type := "perm" )
    gap> AtlasGenerators( "C4", 2 );
    rec( dim := 1, generators := [ [ [ E(4) ] ] ], groupname := "C4", 
      id := "a", identifier := [ [ "priv", "C4" ], "C4G1-Ar1aB0.g", 1, 1 ]
        , repname := "C4G1-Ar1aB0", repnr := 2, size := 4, 
      standardization := 1, type := "matalg" )
    gap> AtlasGenerators( "C4", 3 );
    fail
    gap> AtlasProgram( "C4", "other", "test" );
    rec( groupname := "C4", 
      identifier := [ [ "priv", "C4" ], "C4G1-XtestW1", 1 ], 
      program := <straight line program>, standardization := 1 )
  
  
  We  can  restrict  the data shown by DisplayAtlasInfo (3.5-1) to the private
  directory, as follows.
  
    Example  
    gap> DisplayAtlasInfo( "contents", "priv" );
    group                    | # | maxes | cl | cyc | out | fnd | chk | p*
    -------------------------+---+-------+----+-----+-----+-----+-----+--*
    A5*                      | 1 |       |    |     |     |     |     |  *
    C4*                      | 2 |     1 |    |     |   2 |     |     |  *
  
  
  For checking the data in the private directory, we apply the relevant sanity
  checks (see Section 7.8).
  
    Example  
    gap> if not IsBound( AGR.Test ) then
    >      ReadPackage( "atlasrep", "gap/test.g" );
    >    fi;
    gap> AGR.Test.Words( "priv" );
    true
    gap> AGR.Test.FileHeaders( "priv" );
    true
    gap> AGR.Test.Files( "priv" );
    true
    gap> AGR.Test.BinaryFormat( "priv" );
    true
    gap> AGR.Test.Primitivity( "priv" );
    true
    gap> AGR.Test.Characters( "priv" );
    true
  
  
  Finally,  we  uninstall the private directory, and reset the info level that
  had  been set to 1 in the beginning. (Also the group name C4 is removed this
  way,  which  is  an  advantage  of  using  a toc.g file over calling AGRGNAN
  directly.),  Note  that  we  need  not  remove  the  data  in  the temporary
  directory, GAP will do this automatically.
  
    Example  
    gap> AtlasOfGroupRepresentationsForgetPrivateDirectory( "priv" );
    gap> SetInfoLevel( InfoAtlasRep, level );