  
  [1X3 Private Extensions of the [5XAtlasRep[1X Package[0X
  
  It  may  be  interesting  to use the functions of the [5XGAP[0m interface also for
  representations  or  programs  that  are  [13Xnot[0m  part  of  the  [5XATLAS[0m 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  representations and programs for groups that are declared already
        in the "official" [5XATLAS[0m of Group Representations,
  
  (2)   the  declaration  of  groups  that  are not declared in the "official"
        [5XATLAS[0m  of  Group Representations, and representations and programs for
        them, and
  
  (3)   the definition of new kinds of representations and programs.
  
  The  first two kinds are dealt with in Section [14X3.1[0m and Section [14X3.2[0m. The last
  is described in Section [14X5.5[0m.
  
  Finally, an example of using private extensions is given in Section [14X3.3[0m.
  
  Several  of  the sanity checks for the official part of the [5XAtlasRep[0m package
  make   sense   also   for  private  extensions,  see  Section [14X5.8[0m  for  more
  information.
  
  
  [1X3.1 Adding a Private Data Directory[0X
  
  After the [5XAtlasRep[0m package has been loaded into the [5XGAP[0m session, one can add
  private  data.  However,  one should [13Xnot[0m add private files to the local data
  directories  of the package, or modify files in these 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 [13Xnot[0m automatically replaced by a correct server file.)
  
  [1X3.1-1 AtlasOfGroupRepresentationsNotifyPrivateDirectory[0m
  
  [2X> AtlasOfGroupRepresentationsNotifyPrivateDirectory( [0X[3Xdir[, dirid][0X[2X ) [0Xfunction
  [6XReturns:[0X  [9Xtrue[0m  if  none  of  the  filenames  with  admissible format in the
            directory  [3Xdir[0m  is  contained in other data directories and if the
            data  belongs  to groups whose names have been declared, otherwise
            [9Xfalse[0m.
  
  Let  [3Xdir[0m  be a directory (see [14X'Reference: Directories'[0m) or a string denoting
  the  name of a directory (such that the [5XGAP[0m object describing this directory
  can  be  obtained  by  calling  [2XDirectory[0m  ([14XReference:  Directory[0m)  with the
  argument  [3Xdir[0m).  In the following, let [3Xdirname[0m be the name of the directory.
  So  [3Xdirname[0m can be an absolute path or a path relative to the home directory
  of  the  user  (starting with a tilde character [10X~[0m) or a path relative to the
  directory where [5XGAP[0m was started.
  
  If  the second argument [3Xdirid[0m is given, it must be a string. This value will
  be  used  in  the  [10Xidentifier[0m components of the records that are returned by
  interface  functions  (see  Section [14X2.5[0m) for data contained in the directory
  [3Xdir[0m. Note that the directory name may be different in different [5XGAP[0m sessions
  or  for  different  users  who  want  to  access  the same data, whereas the
  [10Xidentifier[0m  components shall be independent of such differences. The default
  for [3Xdirid[0m is [3Xdirname[0m.
  
  [2XAtlasOfGroupRepresentationsNotifyPrivateDirectory[0m  notifies  the data in the
  directory  [3Xdir[0m to the [5XAtlasRep[0m package. First the pair [10X[ [3Xdirname[0m[10X, [3Xdirid[0m[10X ][0m is
  added  to  the [10Xprivate[0m component of [2XAtlasOfGroupRepresentationsInfo[0m ([14X5.1-5[0m).
  If the directory contains a file with the name [11Xtoc.g[0m then this file is read;
  this  file  is  useful for adding new group names (see [2XAGRGNAN[0m ([14X5.7-1[0m)), for
  adding field information for characteristic zero representations (see [2XAGRRNG[0m
  ([14X5.7-2[0m)),  or for adding new data types (see Section [14X5.5[0m). 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 [14X5.6[0m). Filenames that are already contained in another data directory
  of  the [5XAtlasRep[0m package are ignored, and messages about these filenames are
  printed if the info level of [2XInfoAtlasRep[0m ([14X5.1-1[0m) 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 [2XInfoAtlasRep[0m ([14X5.1-1[0m) 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 [11X.gaprc[0m (see Section [14X'Reference: The .gaprc file'[0m).
  
  [1X3.1-2 AtlasOfGroupRepresentationsForgetPrivateDirectory[0m
  
  [2X> AtlasOfGroupRepresentationsForgetPrivateDirectory( [0X[3Xdirid[0X[2X ) _______[0Xfunction
  
  If  [3Xdirid[0m  is  the  identifier  of  a  private  data directory that has been
  notified with [2XAtlasOfGroupRepresentationsNotifyPrivateDirectory[0m ([14X3.1-1[0m) then
  [2XAtlasOfGroupRepresentationsForgetPrivateDirectory[0m 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.
  
  
  [1X3.2 The Effect of Private Extensions on the User Interface[0X
  
  First suppose that only new groups or new data for known groups are added.
  
  In this case, [2XDisplayAtlasInfo[0m ([14X2.5-1[0m) 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  [10Xmarkprivate[0m  of
  [2XAtlasOfGroupRepresentationsInfo[0m  ([14X5.1-5[0m);  by default, this is a star [10X*[0m. The
  ordering of representations listed by [2XDisplayAtlasInfo[0m ([14X2.5-1[0m) (and referred
  to   by  [2XAtlasGenerators[0m  ([14X2.5-2[0m))  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 [14X2[0m, the only difference is that also
  the   private  data  can  be  accessed.  In  particular  the  "free  format"
  [10X[3Xgroupname[0m[10XG[3Xi[0m[10X-X[3Xdescr[0m[10XW[3Xn[0m[10X[0m  for  straight  line  programs (see Section [14X5.6[0m) may be
  used  in  private  directories;  the  data can be accessed with [2XAtlasProgram[0m
  ([14X2.5-3[0m), where the last two arguments are the strings [10X"other"[0m and [3Xdescr[0m.
  
  If  also private data types are introduced (see Section [14X5.5[0m) then additional
  columns  or  rows  can appear in the output of [2XDisplayAtlasInfo[0m ([14X2.5-1[0m), and
  new  inputs  can become meaningful for all interface functions. Examples for
  these changes can be found in Section [14X3.3[0m.
  
  
  [1X3.3 An Example of Extending the [5XAtlasRep[1X Package[0X
  
  In the beginning we set the info level of [2XInfoAtlasRep[0m ([14X5.1-1[0m) to 1.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> level:= InfoLevel( InfoAtlasRep );;[0X
    [4Xgap> SetInfoLevel( InfoAtlasRep, 1 );[0X
  [4X------------------------------------------------------------------[0X
  
  Let  us assume that the directory [11Xprivdir[0m contains data for the cyclic group
  C_4  of  order  4 and for the symmetric group S_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 [11Xprivdir[0m contains the following files.
  
  [8X[11XC4G1-p4B0.m1[0m[8X[0m
        a faithful permutation representation of C_4 on 4 points,
  
  [8X[11XC4G1-max1W1[0m[8X[0m
        the straight line program that returns the square of its unique input,
  
  [8X[11XC4G1-a2W1[0m[8X[0m
        the  straight  line  program that applies an outer automorphism to its
        unique input,
  
  [8X[11XC4G1-XtestW1[0m[8X[0m
        the straight line program that returns the square of its unique input,
  
  [8X[11XS5G1-p2B0.m1[0m[8X and [11XS5G1-p2B0.m2[0m[8X[0m
        the  permutation representation of the commutator factor group of S_5,
        on 2 points.
  
  The directory and the files can be created as follows.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> pkg:= Filename( DirectoriesPackageLibrary( "atlasrep", "" ), "" );;[0X
    [4Xgap> prv:= DirectoryTemporary( "privdir" );;[0X
    [4Xgap> FileString( Filename( prv, "C4G1-p4B0.m1" ),[0X
    [4X>                MeatAxeString( [ (1,2,3,4) ], 4 ) );;[0X
    [4Xgap> FileString( Filename( prv, "C4G1-max1W1" ),[0X
    [4X>                "inp 1\npwr 2 1 2\noup 1 2\n" );;[0X
    [4Xgap> FileString( Filename( prv, "C4G1-XtestW1" ),[0X
    [4X>                "inp 1\npwr 2 1 2\noup 1 2\n" );;[0X
    [4Xgap> FileString( Filename( prv, "C4G1-a2W1" ),[0X
    [4X>                "inp 1\npwr 3 1 2\noup 1 2\n" );;[0X
    [4Xgap> FileString( Filename( prv, "C4G1-Ar1aB0.g" ),[0X
    [4X>                "return rec( generators:= [ [[E(4)]] ] );\n" );;[0X
    [4Xgap> FileString( Filename( prv, "S5G1-p2B0.m1" ),[0X
    [4X>                MeatAxeString( [ (1,2) ], 2 ) );;[0X
    [4Xgap> FileString( Filename( prv, "S5G1-p2B0.m2" ),[0X
    [4X>                MeatAxeString( [ (1,2) ], 2 ) );;[0X
  [4X------------------------------------------------------------------[0X
  
  (We  could also introduce intermediate directories [11XC4[0m and [11XS5[0m, say, each with
  the  data  for  one  group  only.  Here we do not show this because creating
  directories seems to be not possible without the [5XGAP[0m package [5XIO[0m.)
  
  Now  we create a file whose name is not admissible because it occurs already
  in the official part of the database. (This will cause an info line below.)
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> FileString( Filename( prv, "S5G1-p5B0.m1" ),[0X
    [4X>                MeatAxeString( [ (1,2) ], 5 ) );;[0X
  [4X------------------------------------------------------------------[0X
  
  The official part of the [5XAtlasRep[0m package does not contain information about
  C_4,  so  we  first notify this group, in the file [11Xprivdir/toc.g[0m. (The group
  S_5 is known with name [10XA5.2[0m in the official part of the [5XAtlasRep[0m package, so
  it cannot be notified.)
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> FileString( Filename( prv, "toc.g" ),[0X
    [4X>                "AGRGNAN(\"C4\",\"C4\");\n" );;[0X
  [4X------------------------------------------------------------------[0X
  
  Then we notify the private directory.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> AtlasOfGroupRepresentationsNotifyPrivateDirectory( prv, "priv" );[0X
    [4X#I  file `S5G1-p5B0.m1' was already in another t.o.c.[0X
    [4Xfalse[0X
  [4X------------------------------------------------------------------[0X
  
  (The  nonadmissible  filename  [10XS5G1-p5B0.m1[0m  was  ignored  for  the  private
  directory.  If this file would not be present then the return value would be
  [9Xtrue[0m.)  Now we can use the interface functions for accessing the data in the
  private directory.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> DisplayAtlasInfo( [ "C4" ] );[0X
    [4Xgroup    #  maxes  cl  cyc  out  find  check  pres[0X
    [4X--------------------------------------------------[0X
    [4XC4*      2      1   -    -    2     -      -     -[0X
    [4Xgap> DisplayAtlasInfo( "C4" );[0X
    [4XRepresentations for G = C4:    (all refer to std. generators 1)[0X
    [4X---------------------------[0X
    [4X1: G <= Sym(4)*[0X
    [4X2: G <= GL(1a,C)*[0X
    [4X[0X
    [4XPrograms for G = C4:    (all refer to std. generators 1)[0X
    [4X--------------------[0X
    [4Xavailable maxes of G:  [ 1 ]*[0X
    [4Xavailable automorphisms:  [ "2" ]*[0X
    [4Xavailable other scripts:[0X
    [4X   "test"*[0X
    [4Xgap> DisplayAtlasInfo( "C4", IsPermGroup, true );[0X
    [4XRepresentations for G = C4:    (all refer to std. generators 1)[0X
    [4X---------------------------[0X
    [4X1: G <= Sym(4)*[0X
    [4Xgap> DisplayAtlasInfo( "C4", IsMatrixGroup );[0X
    [4XRepresentations for G = C4:    (all refer to std. generators 1)[0X
    [4X---------------------------[0X
    [4X2: G <= GL(1a,C)*[0X
    [4Xgap> DisplayAtlasInfo( "C4", Dimension, 2 );[0X
    [4Xgap> DisplayAtlasInfo( "A5.2", NrMovedPoints, 2 );[0X
    [4XRepresentations for G = A5.2:    (all refer to std. generators 1)[0X
    [4X-----------------------------[0X
    [4X4: G <= Sym(2)*[0X
    [4Xgap> info:= OneAtlasGeneratingSetInfo( "C4" );[0X
    [4Xrec( groupname := "C4", standardization := 1, repnr := 1, [0X
    [4X  identifier := [ [ "priv", "C4" ], [ "C4G1-p4B0.m1" ], 1, 4 ], p := 4, [0X
    [4X  id := "" )[0X
    [4Xgap> AtlasGenerators( info.identifier );[0X
    [4Xrec( generators := [ (1,2,3,4) ], groupname := "C4", standardization := 1,[0X
    [4X  repnr := 1, identifier := [ [ "priv", "C4" ], [ "C4G1-p4B0.m1" ], 1, 4 ], [0X
    [4X  p := 4, id := "" )[0X
    [4Xgap> AtlasProgram( "C4", 1 );[0X
    [4Xrec( program := <straight line program>, standardization := 1, [0X
    [4X  identifier := [ [ "priv", "C4" ], "C4G1-max1W1", 1 ], groupname := "C4" )[0X
    [4Xgap> AtlasProgram( "C4", "maxes", 1 );[0X
    [4Xrec( program := <straight line program>, standardization := 1, [0X
    [4X  identifier := [ [ "priv", "C4" ], "C4G1-max1W1", 1 ], groupname := "C4" )[0X
    [4Xgap> AtlasProgram( "C4", "maxes", 2 );[0X
    [4Xfail[0X
    [4Xgap> AtlasGenerators( "C4", 1 );[0X
    [4Xrec( generators := [ (1,2,3,4) ], groupname := "C4", standardization := 1,[0X
    [4X  repnr := 1, identifier := [ [ "priv", "C4" ], [ "C4G1-p4B0.m1" ], 1, 4 ], [0X
    [4X  p := 4, id := "" )[0X
    [4Xgap> AtlasGenerators( "C4", 2 );[0X
    [4Xrec( generators := [ [ [ E(4) ] ] ], groupname := "C4", standardization := 1,[0X
    [4X  repnr := 2, identifier := [ [ "priv", "C4" ], "C4G1-Ar1aB0.g", 1, 1 ], [0X
    [4X  dim := 1, id := "a" )[0X
    [4Xgap> AtlasGenerators( "C4", 3 );[0X
    [4Xfail[0X
    [4Xgap> AtlasProgram( "C4", "other", "test" );[0X
    [4Xrec( program := <straight line program>, standardization := 1, [0X
    [4X  identifier := [ [ "priv", "C4" ], "C4G1-XtestW1", 1 ], groupname := "C4" )[0X
  [4X------------------------------------------------------------------[0X
  
  For  checking the data in the private directory, we apply some of the sanity
  checks (see Section [14X5.8[0m).
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> AtlasOfGroupRepresentationsTestWords( "priv" );[0X
    [4Xtrue[0X
    [4Xgap> AtlasOfGroupRepresentationsTestFileHeaders( "priv" );[0X
    [4Xtrue[0X
  [4X------------------------------------------------------------------[0X
  
  Finally, we "uninstall" the private directory, and reset the info level that
  had  been set to 1 in the beginning. (Also the group name [10XC4[0m is removed this
  way,  which  is  an  advantage  of  using  a [11Xtoc.g[0m file over calling [2XAGRGNAN[0m
  ([14X5.7-1[0m)  directly.),  Note that we need not remove the data in the temporary
  directory, [5XGAP[0m will do this automatically.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> AtlasOfGroupRepresentationsForgetPrivateDirectory( "priv" );[0X
    [4Xgap> SetInfoLevel( InfoAtlasRep, level );[0X
  [4X------------------------------------------------------------------[0X
  
