Goto Chapter: Top 1 2 3 4 5 6 7 Bib Ind
 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 

4 Customizations of the AtlasRep Package
 4.1 Installing the AtlasRep Package
 4.2 Maintaining the Local Data of the AtlasRep Package
 4.3 User Parameters for the AtlasRep Package
 4.4 Web Services for the AtlasRep Package
 4.5 Extending the ATLAS Database

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.

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

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

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 R.A.Wilson@qmul.ac.uk.

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.

 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 
Goto Chapter: Top 1 2 3 4 5 6 7 Bib Ind

generated by GAPDoc2HTML