GAP (AtlasRep) - Chapter 4: Customizations of the AtlasRep Package

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

[MathJax off]

4 Customizations of the AtlasRep Package
4.1 Installing the AtlasRep Package
4.2 User Preferences of the AtlasRep Package
4.2-1 User preference `AtlasRepAccessRemoteFiles`
4.2-2 User preference `AtlasRepDataDirectory`
4.2-3 User preference `AtlasRepTOCData`
4.2-4 User preference `CompressDownloadedMeatAxeFiles`
4.2-5 User preference `FileAccessFunctions`
4.2-6 User preference `AtlasRepLocalServerPath`
4.2-7 User preference `HowToReadMeatAxeTextFiles`
4.2-8 User preference `WriteHeaderFormatOfMeatAxeFiles`
4.2-9 User preference `WriteMeatAxeFilesOfMode2`
4.2-10 User preference `BaseOfMeatAxePermutation`
4.2-11 User preference `DisplayFunction`
4.2-12 User preference `AtlasRepMarkNonCoreData`
4.2-13 User preference `DebugFileLoading`
4.2-14 User preference `AtlasRepJsonFilesAddresses`
4.3 Web Contents for the AtlasRep Package
4.4 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 somewhere else, see Section Reference: GAP Root Directories. The latter possibility must be chosen if you do not have write access to the GAP root directory.

If it is likely that you 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.

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.2-2, the defaults are the subdirectories `data*` 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 Apr 12 12:34 dataext
    drwxrwxrwt   3 you      you          1024 Apr 12 12:34 datagens
    drwxrwxrwt   3 you      you          1024 Apr 12 12:34 datapkg
    drwxrwxrwt   3 you      you          1024 Apr 12 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.

PDF, HTML, and text versions of the package manual are available in the `doc` directory of the package.

#### 4.2 User Preferences of the AtlasRep Package

This section describes global parameters for which it might make sense to change their defaults, using GAP's user preferences (see Reference: Configuring User preferences).

- Is access to remote data allowed (see Section 4.2-1)? If yes then also the following parameters are of interest.

  - From where can the data be fetched (see Section 4.2-3)?

  - Where are local copies of these data stored (see Section 4.2-2)?

  - Shall files be compressed after they have been downloaded (see Section 4.2-4)?

- The following parameters influence reading and writing of local files.

  - What shall actually happen when data are requested by the interface functions (see Section 4.2-5)?

  - If the value of the user preference `FileAccessFunctions` contains `"direct access to a local server"`, what is its path (see Section 4.2-6)?

  - Shall `ScanMeatAxeFile` (7.3-1) focus on small runtime or on small space when reading MeatAxe text files (see Section 4.2-7)?

  - Which kind of headers shall `MeatAxeString` (7.3-2) create (see Section 4.2-8)?

  - Shall `MeatAxeString` (7.3-2) interpret permutation matrices more as permutations (mode 2) or as matrices (mode 1 or 6) (see Section 4.2-9)?

  - Shall the default for `CMtxBinaryFFMatOrPerm` (7.3-4) be to write binary files of zero-based or one-based permutations (see Section 4.2-10)?

- Which function is used by `DisplayAtlasInfo` (3.6-1) for printing to the screen (see Section 4.2-11)?

- How does `DisplayAtlasInfo` (3.6-1) mark data that do not belong to the core database (see Section 4.2-12)?

- Shall debug messages be printed when local data files are read (see Section 4.2-13)?

##### 4.2-1 User preference `AtlasRepAccessRemoteFiles`

The value `true` (the default) allows the AtlasRep package to fetch data files that are not yet locally available. If the value is `false` then only those data files can be used that are available locally.

If you are working offline then you should set the value to `false`.

Changing the value in a running GAP session does not affect the information shown by `DisplayAtlasInfo` (3.6-1), this information depends on the value of the preference at the time when the AtlasRep package and its data extensions get loaded.

##### 4.2-2 User preference `AtlasRepDataDirectory`

The value must be a string that is either empty or the filename of a directory (in the sense of `IsDirectoryPath` (Reference: IsDirectoryPath)) that contains the directories in which downloaded data will be stored.

An empty string means that downloaded data are just kept in the GAP session but not saved to local files.

In the following situations, a nonempty default value is computed. If the current GAP session is running inside a Julia session then a Julia scratchspace is taken. Otherwise, if the subdirectories `dataext`, `datagens`, `dataword` of the AtlasRep directory are writable for the user then the installation path of the AtlasRep package (including a trailing slash symbol) is taken. In all other cases, the default is an empty string.

##### 4.2-3 User preference `AtlasRepTOCData`

The value must be a list of strings of the form `"ID|address"` where `ID` is the id of a part of the database and `address` is an URL or a file path (as an absolute path or relative to the user's home directory, cf. `Directory` (Reference: Directory)) of a readable JSON format file that contains the table of contents of this part, see `StringOfAtlasTableOfContents` (5.1-3).

The default lists four entries: the core database, the data distributed with the AtlasRep package, and the data that belong to the packages MFER and CTBlocks.

##### 4.2-4 User preference `CompressDownloadedMeatAxeFiles`

When used with UNIX, GAP can read `gzip`ped files, see Reference: Saving and Loading a Workspace. If the package's user preference `CompressDownloadedMeatAxeFiles` has the value `true` then each MeatAxe format text file that is downloaded from the internet is afterwards compressed with `gzip`. The default value is `false`.

Compressing files 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 2.0 the core database contained about \(8\,400\) data files in MeatAxe format, which needed about \(1\,400\) MB in uncompressed text format and about \(275\) MB in compressed text format.

##### 4.2-5 User preference `FileAccessFunctions`

This preference allows one to customize what actually happens when data are requested by the interface functions: Is it necessary to download some files? If yes then which files are downloaded? If no then which files are actually read into GAP?

Currently one can choose among the following features.

1. Download/read MeatAxe text files.

2. Prefer downloading/reading MeatAxe binary files.

3. Prefer reading locally available data files.

(Of course files can be downloaded only if the user preference `AtlasRepAccessRemoteFiles` has the value `true`, see Section 4.2-1.)

This feature could be used more generally, see Section 7.2 for technical details and the possibility to add other features.

##### 4.2-6 User preference `AtlasRepLocalServerPath`

If the data of the core database are available locally (for example because one has access to a local mirror of the data) then one may prefer reading these files instead of downloading data. In order to achieve this, one can set the user preference `AtlasRepLocalServerPath` and add `"direct access to a local server"` to the user preference `FileAccessFunctions`, see Section 4.2-5.

The value must be a string that is the filename of a directory (in the sense of `IsDirectoryPath` (Reference: IsDirectoryPath)) that contains the data of the ATLAS of Group Representations, in the same directory tree structure as on the ATLAS server.

##### 4.2-7 User preference `HowToReadMeatAxeTextFiles`

The value `"fast"` means that `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); this 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. For example, a \(4\,370\) by \(4\,370\) 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. This means that when one reads the file with the fast variant, GAP will temporarily grow by more than this value.

Note that this parameter has an effect 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.2-8 User preference `WriteHeaderFormatOfMeatAxeFiles`

This user preference determines the format of the header lines of MeatAxe format strings created by `MeatAxeString` (7.3-2), see the `C`-MeatAxe manual [Rin] for details. The following values are supported.

`"numeric"`

  means that the header line of the returned string consists of four integers (in the case of a matrix these are mode, row number, column number and field size),

`"numeric (fixed)"`

  means that the header line of the returned string consists of four integers as in the case `"numeric"`, but additionally each integer is right aligned in a substring of length (at least) six,

`"textual"`

  means that the header line of the returned string consists of assignments such as `matrix field=2`.

##### 4.2-9 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.2-10 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.

##### 4.2-11 User preference `DisplayFunction`

The way how `DisplayAtlasInfo` (3.6-1) shows the requested overview is controlled by the package AtlasRep's user preference `DisplayFunction`. The value must be a string that evaluates to a GAP function. The default value is `"Print"` (see `Print` (Reference: Print)), other useful values are `"PrintFormattedString"` (see `PrintFormattedString` (GAPDoc: PrintFormattedString)) and `"AGR.Pager"`; the latter means that `Pager` (Reference: Pager) is called with the `formatted` option, which is necessary for switching off GAP's automatic line breaking.

##### 4.2-12 User preference `AtlasRepMarkNonCoreData`

The value is a string (the default is a star '*') that is used in `DisplayAtlasInfo` (3.6-1) to mark data that do not belong to the core database, see Section 5.2.

##### 4.2-13 User preference `DebugFileLoading`

If the value is `true` then debug messages are printed before and after data files get loaded. The default value is `false`.

##### 4.2-14 User preference `AtlasRepJsonFilesAddresses`

The value, if set, must be a list of length two, the first entry being an URL describing a directory that contains Json format files of the available matrix representations in characteristic zero, and the second being a directory path where these files shall be stored locally. If the value is set, then the functions of the package use the Json format files instead of the GAP format files. The default for the local path is an empty string, meaning that the local directory given by the user preference `AtlasRepDataDirectory` (see Section 4.2-2) is used.

#### 4.3 Web Contents for the AtlasRep Package

The home page of the AtlasRep package provides

- package archives,

- introductory package information,

- the current table of contents of core data in the file `atlasprm.json` of the package, cf. `StringOfAtlasTableOfContents` (5.1-3),

- the list of changes of remote core data files,

- a starter archive containing many small representations and programs, and

- an overview of the core data in a similar format as the information shown by the function `DisplayAtlasInfo` (3.6-1) of the package; more details can be found on the home page of the ATLAS of Group Representations.

#### 4.4 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 make additional representations and programs accessible for the GAP interface, and to use these private data in the same way as the core 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