chap4.txt

  
  4 Customizations of the AtlasRep Package
  
  
  4.1 Installing the AtlasRep Package
  
  To  install  the  package, unpack the archive file in a directory in the pkg
  directory  of  your  local copy of GAP 4. This might be the pkg directory of
  the  GAP 4  root  directory,  see 'Reference:  Installing a GAP Package' for
  details.  It is however also possible to keep an additional pkg directory in
  your private directories, see Section 'Reference: GAP Root Directories'. The
  latter possibility must be chosen if you do not have write access to the GAP
  root directory.
  
  Data  files that are available from an earlier version of the package are in
  principle                                                              kept;
  see AtlasOfGroupRepresentationsTestTableOfContentsRemoteUpdates  (4.2-4) for
  necessary updates.
  
  If  it  is  likely that one will work offline, it makes sense to install the
  starter archive that can be downloaded from the package's homepage.
  
  The  package  consists entirely of GAP code, no external binaries need to be
  compiled  for  the package itself. However, if the GAP package IO [Neu14] is
  used  to  access  remote  data  files  (see Section 4.3-3) then its external
  binary must be available.
  
  After  unpacking  the  package  archive,  the  write  permissions  for those
  directories  should  be  checked into which users will download files. Every
  user can customize these paths via a user preference, see Section 4.3-9, the
  defaults  are  the  subdirectories  datagens  and  dataword  of  the package
  directory.   The   recommended   permissions  under  UNIX  for  the  default
  directories are set as follows.
  
    Example  
    you@unix> chmod 1777 atlasrep/data*
    you@unix> ls -ld atlasrep/data*
    drwxrwxrwt   3 you      you          1024 Oct 31 12:34 datagens
    drwxrwxrwt   3 you      you          1024 Oct 31 12:34 dataword
  
  
  For checking the installation of the package, you should start GAP and call
  
    Example  
    gap> ReadPackage( "atlasrep", "tst/testinst.g" );
  
  
  If  the  installation  is  o.k. then the GAP prompt appears without anything
  else  being  printed;  otherwise  the  output  lines tell you what should be
  changed.
  
  More  test  files  are  available  in  the tst directory of the package, see
  Section  7.8 for details.
  
  PDF,  HTML, and text versions of the package manual are available in the doc
  directory of the package.
  
  
  4.2 Maintaining the Local Data of the AtlasRep Package
  
  The  current  table  of  contents  of  the database is contained in the file
  gap/atlasprm.g  of  the  AtlasRep package. This file is read by default when
  the  package is loaded. It may happen that new data files have been added to
  the  servers  since  the  last  release  of the AtlasRep package, thus it is
  useful to update the table of contents of the package from time to time.
  
  For  that,  one can fetch the most recent version of the file gap/atlasprm.g
  from   the   home   page   of  the  package  (see  Section 4.4),  either  by
  calling ReloadAtlasTableOfContents  (4.2-1)  in a GAP session or by hand. In
  the  latter  case,  the  new  file can then be read into the GAP session via
  ReplaceAtlasTableOfContents  (4.2-3).  Alternatively,  one can add a line to
  the  user's gaprc file (see 'Reference: The gap.ini and gaprc files'), which
  assigns the filename of the current gap/atlasprm.g file (as an absolute path
  or   relative  to  the  user's  home  directory,  cf. Directory  (Reference:
  Directory)) to the global variable ATLASREP_TOCFILE; in this case, this file
  is read instead of the one from the package distribution when the package is
  loaded.
  
  Users  who  have write access to the directory where the AtlasRep package is
  installed  can  alternatively use the maketoc script in the etc directory of
  the  package  for  regularly updating the file gap/atlasprm.g. Users without
  this  write  access can store the new file in a different place, and read it
  with ReplaceAtlasTableOfContents (4.2-3).
  
  4.2-1 ReloadAtlasTableOfContents
  
  ReloadAtlasTableOfContents( dirname )  function
  Returns:  fail  if  the  required  table  of contents could not be reloaded,
            otherwise true.
  
  Let dirname be a string, which must be one of "remote", "local", or the name
  of a private data directory (see Chapter 5).
  
  In  the  case of "remote", the file atlasprm.g is fetched from the package's
  home page, and then read into GAP. In the case of "local", the subset of the
  data  listed  in  the  "remote"  table  of  contents  is considered that are
  actually  available  in the local data directories. In the case of a private
  directory,  its contents is inspected, and the table of contents for dirname
  is  replaced  by the one obtained from inspecting the actual contents of the
  data directories (see Section 7.7).
  
  4.2-2 StoreAtlasTableOfContents
  
  StoreAtlasTableOfContents( filename )  function
  
  Let  filename be a string. This function prints the loaded table of contents
  of the servers to the file with name filename.
  
  4.2-3 ReplaceAtlasTableOfContents
  
  ReplaceAtlasTableOfContents( filename )  function
  
  Let   filename   be   the  name  of  a  file  that  has  been  created  with
  StoreAtlasTableOfContents (4.2-2).
  
  ReplaceAtlasTableOfContents  first  removes  the  information  that  GAP has
  stored  about  the table of contents of the servers, and then reads the file
  with  name  filename,  thus replacing the previous information by the stored
  one.
  
  4.2-4 AtlasOfGroupRepresentationsTestTableOfContentsRemoteUpdates
  
  AtlasOfGroupRepresentationsTestTableOfContentsRemoteUpdates(  )  function
  Returns:  the  list of names of all locally available data files that should
            be removed.
  
  This  function  fetches  the file changes.html from the package's home page,
  extracts  the  times of changes for the data files in question, and compares
  them  with  the times of the last changes of the local data files. For that,
  the  GAP  package IO [Neu14] is needed; if it is not available then an error
  message is printed, and fail is returned.
  
  If  the time of the last modification of a server file is later than that of
  the  local  copy  then  the  local  file  must  be updated. (This means that
  touching files in the local directories will cheat this function.)
  
  It  is  useful  that  a  system  administrator  (i. e.,  someone who has the
  permission  to  remove  files  from the data directories) runs this function
  from  time  to  time,  and  afterwards removes the files in the list that is
  returned.   This   way,   new  versions  of  these  files  will  be  fetched
  automatically from the servers when a user asks for their data.
  
  
  4.3 User Parameters for the AtlasRep Package
  
  This section lists global parameters for which it might make sense to change
  their     defaults    by    assignments    to    global    variables    (see
  AtlasOfGroupRepresentationsUserParameters  (4.3-8)  for an overview of these
  parameters)  or  using  GAP's  user preferences (see 'Reference: Configuring
  User preferences').
  
  
  4.3-1 Local or Remote Access
  
  There are two possibilities to use the AtlasRep package.
  
  Local access only (offline)
        You  can  restrict  the access to the data that are actually stored in
        the local installation of GAP.
  
  Remote access (online)
        If your computer is connected to a network that provides access to the
        ATLAS  data  (for  example  the  internet)  then  the functions of the
        package may fetch the requested data automatically from remote servers
        when  they  are  required  for  the first time; these data are then by
        default  stored  in  the  local copy, so later access to them needs no
        network transfer.
  
  The  latter  possibility  is presently not used by other GAP packages, so it
  may  be  regarded as an important feature of the AtlasRep package. Anyhow it
  requires a few words of explanation.
  
  The  possibility  of  online access reflects in particular the fact that the
  ATLAS  of  Group  Representations  is  designed  as  an open database, it is
  expected  to  grow.  As  soon  as  the  developers  of  the  ATLAS  of Group
  Representations  add  new  information  to  the  servers,  these data become
  available  in  GAP  when remote access is enabled, after one has updated the
  corresponding table of contents (see Section 4.2).
  
  Remote access is enabled if and only if the value of the remote component of
  the  global variable AtlasOfGroupRepresentationsInfo (7.1-6) is true. If one
  wants  to  work offline, i.e., if one does not want GAP to attempt accessing
  remote data then this value must be set to false.
  
  Conversely,  if  the  default  value  of  the  remote  component in your GAP
  installation  is  false  then  changing  this  value  to  true  may  be  not
  successful.  First,  it  might  be the case that no server is reachable. And
  second,  if  one can in principle download files from a server then it might
  be  impossible  to actually store these files in the data directories of the
  installed  package;  in  this  case,  it  is  advisable to install the whole
  package or just its data directories in a private directory, see 'Reference:
  GAP Root Directories' for details.
  
  
  4.3-2 Adding and Removing Servers
  
  When access to remote data is enabled (see Section 4.3-1) then the available
  servers   are  given  by  the  servers  component  of  the  global  variable
  AtlasOfGroupRepresentationsInfo (7.1-6).
  
  Removing entries from this list means to disable access to the corresponding
  servers, adding entries makes the corresponding servers available. Of course
  the  latter makes sense only if the new servers really exist, for example in
  a local network.
  
  Currently  there  is just one remote server. As soon as other servers become
  available,  or  a  server name is changed which makes it necessary to adjust
  the  servers  component,  this  will  be  announced  in  the  GAP Forum, cf.
  'Tutorial:  Further  Information about GAP'. The same holds when upgrades of
  the package become available.
  
  
  4.3-3 Accessing Data Files with the GAP Package IO or with wget
  
  When  access  to  remote  data is enabled (see Section 4.3-1) then one needs
  either the GAP package IO [Neu14] or the external program wget for accessing
  data files.
  
  The  chosen  alternative  is given by the value of the wget component of the
  global variable AtlasOfGroupRepresentationsInfo (7.1-6).
  
  If  this  component has the value true then only wget is tried, if the value
  is false then only the IO package is used. If this component is not bound or
  bound  to  another  value than true or false (this is also the default) then
  the  IO  package  is  preferred  to  wget  if this package is available, and
  otherwise wget is tried.
  
  Note  that  the  system  program  wget may be not available, and that it may
  require  some  work  to  install it; hints for that can be found on the home
  page of the AtlasRep package (see Section 4.4).
  
  
  4.3-4 Compressed or Uncompressed Data Files
  
  When  used with UNIX, GAP can read gzipped files, see 'Reference: Saving and
  Loading     a     Workspace'.     If     the     component    compress    of
  AtlasOfGroupRepresentationsInfo (7.1-6) has the value true then each MeatAxe
  format  file  that  is fetched from a remote server is afterwards compressed
  with  gzip.  This  saves  a  lot  of  space if many MeatAxe format files are
  accessed.  (Note  that  data  files  in  other  formats are very small.) For
  example,  at  the time of the release of version 1.5.1 there were about 8400
  data  files  in  MeatAxe  format, which needed about 1400 MB in uncompressed
  text  format  and  about 275 MB in compressed text format. The default value
  for the component compress is false.
  
  
  4.3-5 Customizing DisplayAtlasInfo
  
  The  way  how  DisplayAtlasInfo  (3.5-1)  shows  the  requested  overview is
  controlled       by       the       component       displayFunction       of
  AtlasOfGroupRepresentationsInfo   (7.1-6).   The   default  value  is  Print
  (Reference:  Print),  other  useful values are PrintFormattedString (GAPDoc:
  PrintFormattedString)  and  AGR.Pager;  the  latter  calls Pager (Reference:
  Pager) with the formatted option, which is necessary for switching off GAP's
  automatic line breaking.
  
  
  4.3-6 Customizing the Access to Data Files
  
  By  default,  local data files are stored in the subdirectories datagens and
  dataword of the directory given by the user preference AtlasRepDataDirectory
  (see  Section  4.3-9),  and the files are exactly the text files provided on
  the servers. However, a more flexible approach may be useful.
  
  First,  one  may want to use different file formats, for example the MeatAxe
  binary  files  that are provided by the servers parallel to the MeatAxe text
  files.  Second,  one  may  want  to use a different directory structure, for
  example  the  same  structure  as  used on the servers –this makes sense for
  example  if  a  local  mirror of a server is available, because then one can
  read the server files directly, without transferring/copying them to another
  directory.
  
  As  a  consequence, one would like to customize the meaning of the following
  three access steps.
  
  Are the required files locally available?
        The  required files may have a different name or a different path, and
        the data can be available in one file or can be distributed to several
        files.
  
  How can a file be made locally available?
        A  different  server file may be fetched or some postprocessing may be
        required.
  
  How is the data of a file accessed by GAP?
        A different function may be needed to read the file.
  
  Details how to achieve these customizations can be found in Section 7.2.
  
  
  4.3-7 Reading Large Matrices over Finite Fields
  
  Matrices over finite fields in GAP can be represented in a compressed format
  that  needs  less  space  than  the  corresponding text file. Such a MeatAxe
  format  text file can be read by ScanMeatAxeFile (7.3-1) either line by line
  (which  is  the  default) or as a whole; the latter is faster but needs more
  space  than  the  former.  For example, a 4370 by 4370 matrix over the field
  with  two  elements (as occurs for an irreducible representation of the Baby
  Monster)  requires less than 3 MB space in GAP but the corresponding MeatAxe
  format  text  file is more than 19 MB large, which means that when one reads
  the  file with the fast variant, GAP will temporarily grow by more than this
  value.   One   can   change   the   mode  by  setting  the  global  variable
  CMeatAxe.FastRead (7.1-4) to true or false, respectively.
  
  Note  that this parameter is meaningful only when ScanMeatAxeFile (7.3-1) is
  used.  It  has  no  effect  for  example  if  MeatAxe binary files are read,
  cf. FFMatOrPermCMtxBinary (7.3-5).
  
  4.3-8 AtlasOfGroupRepresentationsUserParameters
  
  AtlasOfGroupRepresentationsUserParameters(  )  function
  
  This  function  returns  a  string that describes an overview of the current
  values  of the user parameters introduced in this section. One can use Print
  (Reference: Print) or Pager (Reference: Pager) for showing the overview.
  
  
  4.3-9 User preference AtlasRepDataDirectory
  
  The value must be a string that is the filename of a directory (in the sense
  of   IsDirectoryPath   (Reference:   IsDirectoryPath))   that  contains  the
  directories  datagens  and dataword in which downloaded data will be stored.
  The  default  is  the installation path of the AtlasRep package (including a
  trailing slash symbol).
  
  
  4.3-10 User preference WriteMeatAxeFilesOfMode2
  
  The  value  true  means  that the function MeatAxeString (7.3-2) will encode
  permutation  matrices  via  mode 2 descriptions, that is, the first entry in
  the  header  line is 2, and the following lines contain the positions of the
  nonzero  entries.  If  the  value  is false (the default) then MeatAxeString
  (7.3-2) encodes permutation matrices via mode 1 or mode 6 descriptions, that
  is, the lines contain the matrix entries.
  
  
  4.3-11 User preference BaseOfMeatAxePermutation
  
  The  value  0  means  that the function CMtxBinaryFFMatOrPerm (7.3-4) writes
  zero-based  permutations,  that is, permutations acting on the points from 0
  to the degree minus one; this is achieved by shifting down all images of the
  GAP permutation by one. The value 1 (the default) means that the permutation
  stored in the binary file acts on the points from 1 to the degree.
  
  Up to version 2.3 of the C-MeatAxe, permutations in binary files were always
  one-based.  Zero-based  permutations  were  introduced in version 2.4, which
  still is able to read files containing one-based permutations.
  
  
  4.4 Web Services for the AtlasRep Package
  
  The home page of the AtlasRep package is
  
  http://www.math.rwth-aachen.de/~Thomas.Breuer/atlasrep.
  
  Besides package archives and introductory package information, it provides
  
      the  current  file with the table of contents (the file gap/atlasprm.g
        of                  the                  package,                  see
        http://www.math.rwth-aachen.de/~Thomas.Breuer/atlasrep/atlasprm.g),
        cf. ReloadAtlasTableOfContents (4.2-1),
  
      a  starter  archive containing many small representations and programs
        (see
        http://www.math.rwth-aachen.de/~Thomas.Breuer/atlasrep/atlasrepdata.tar.gz),
  
      the   list   of   changes   of   server  files  in  HTML  format  (see
        http://www.math.rwth-aachen.de/~Thomas.Breuer/atlasrep/htm/data/changes.htm),
        cf. AtlasOfGroupRepresentationsTestTableOfContentsRemoteUpdates
        (4.2-4), and
  
      an  overview  of the data available via the GAP interface to the ATLAS
        of      Group     Representations,     in     HTML     format     (see
        http://www.math.rwth-aachen.de/~Thomas.Breuer/atlasrep/htm/data/overview.htm);
        this  is similar to the information shown by DisplayAtlasInfo (3.5-1),
        further  information  can  be found on the home page of the ATLAS, see
        http://brauer.maths.qmul.ac.uk/Atlas.
  
  
  4.5 Extending the ATLAS Database
  
  Users  who  have  computed new representations that might be interesting for
  inclusion  into  the  ATLAS  of  Group  representations can send the data in
  question to mailto:[email protected].
  
  It  is  also possible to store private representations and programs in local
  directories,  and  to  use  them  in  the same way as the official data. See
  Chapter 5 for details.