Goto Chapter: Top 1 2 3 4 5 6 7 Bib Ind

### 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. However, if the GAP package IO [Neu14] is used to access remote data files (see Section 4.2-4) 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.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)?

• How are these data transfered (see Section 4.2-4)?

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

• 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-6)?

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

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

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

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

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

• Which function is used by DisplayAtlasInfo (3.5-1) for printing to the screen (see Section 4.2-12)?

• How does DisplayAtlasInfo (3.5-1) mark data that do not belong to the core database (see Section 4.2-13)?

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

##### 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.5-1), this information depends on the value of the preference at the time when the extension gets loaded.

##### 4.2-2 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 in which downloaded data will be stored. The default is the installation path of the AtlasRep package (including a trailing slash symbol).

##### 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 contain 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 FileTransferTool

This user preference must be set if the user preference AtlasRepAccessRemoteFiles has the value true, see Section 4.2-1. In this case, one needs either the GAP package IO [Neu14] or the external program wget for accessing data files.

Which alternative is chosen at runtime is given by the value of the package's user preference FileTransferTool.

The value "wget" means that only wget is tried. The value "io" means that only the IO package is used. The value "prefer io to wget" (the default) means that the IO package is used 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.3).

##### 4.2-5 User preference CompressDownloadedMeatAxeFiles

When used with UNIX, GAP can read gzipped 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 8400 data files in MeatAxe format, which needed about 1400 MB in uncompressed text format and about 275 MB in compressed text format.

##### 4.2-6 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.

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-7 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-6.

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-8 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 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. 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-9 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-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.2-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.

##### 4.2-12 User preference DisplayFunction

The way how DisplayAtlasInfo (3.5-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-13 User preference AtlasRepMarkNonCoreData

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

##### 4.2-14 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.