GAP (ResClasses) - Chapter 4: Installation and Auxiliary Functions

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

[MathJax on]

4 Installation and Auxiliary Functions
4.1 Requirements
4.2 Installation
4.3 The testing routines
4.3-1 ResClassesTest
4.3-2 ResClassesTestExamples
4.4 Utilities for preparing the package for distribution
4.4-1 ResClassesBuildManual
4.4-2 ConvertPackageFilesToUNIXLineBreaks
4.4-3 RemoveTemporaryPackageFiles
4.5 Creating timestamped logfiles
4.5-1 LogToDatedFile
4.6 DownloadFile, SendEmail and EmailLogFile
4.6-1 DownloadFile
4.6-2 SendEmail
4.6-3 EmailLogFile
4.7 Creating bitmap pictures
4.7-1 SaveAsBitmapPicture
4.7-2 DrawLineNC
4.8 Some general utility functions

### 4 Installation and Auxiliary Functions

#### 4.1 Requirements

This version of ResClasses needs at least GAP 4.9.0, Polycyclic 2.11 [EHN13], GAPDoc 1.5.1 [LN12] and Utils 0.40 [GKW16]. It can be used on all platforms for which GAP is available. ResClasses is completely written in the GAP language and does neither contain nor require external binaries.

#### 4.2 Installation

Like any other GAP package, ResClasses is usually installed in the `pkg` subdirectory of the GAP distribution. This is accomplished by extracting the distribution file in this directory. By default, the package ResClasses is autoloaded. If you have switched autoloading of packages off, you can load ResClasses via `LoadPackage( "resclasses" );`.

#### 4.3 The testing routines

##### 4.3-1 ResClassesTest

`‣ ResClassesTest`( ) | ( function )

Returns: `true` if no errors were found, and `false` otherwise.

Performs tests of the ResClasses package. Errors, i.e. differences to the correct results of the test computations, are reported. The processed test files are in the directory `pkg/resclasses/tst`.

##### 4.3-2 ResClassesTestExamples

`‣ ResClassesTestExamples`( ) | ( function )

Returns: nothing.

Runs all examples in the manual of the ResClasses package, and reports any differences between the actual output and the output printed in the manual.

#### 4.4 Utilities for preparing the package for distribution

##### 4.4-1 ResClassesBuildManual

`‣ ResClassesBuildManual`( ) | ( function )

Returns: nothing.

This function is a development tool which builds the manual of the ResClasses package in the file formats LaTeX, PDF, HTML and ASCII text. This is accomplished using the GAPDoc package by Frank Lübeck and Max Neunhöffer. Building the manual is possible only on UNIX-type systems and requires PDFLaTeX. As all files generated by this function are included in the distribution file anyway, users will not need it.

##### 4.4-2 ConvertPackageFilesToUNIXLineBreaks

`‣ ConvertPackageFilesToUNIXLineBreaks`( package ) | ( function )

Returns: nothing.

This function is a development tool which converts the text files of package package from Windows- to UNIX line breaks. Here package is assumed to be either `"resclasses"` or `"rcwa"`.

##### 4.4-3 RemoveTemporaryPackageFiles

`‣ RemoveTemporaryPackageFiles`( package ) | ( function )

Returns: nothing.

This function is a development tool which cleans up the temporary files of package package. Here package is assumed to be either `"resclasses"` or `"rcwa"`.

#### 4.5 Creating timestamped logfiles

##### 4.5-1 LogToDatedFile

`‣ LogToDatedFile`( directory ) | ( function )

Returns: the full pathname of the created logfile.

This function opens a logfile in the specified directory; the name of the logfile has the form of a timestamp, i.e. `year-month-day hour-minute-second.log.` If GAP is already in logging mode, the old logfile is closed before the new one is opened.

The availability of this function depends on that the package IO [HN16] is installed and compiled.

#### 4.6 DownloadFile, SendEmail and EmailLogFile

##### 4.6-1 DownloadFile

`‣ DownloadFile`( url ) | ( function )

Returns: the contents of the file with URL url in the form of a string if that file exists and the download was successful, and `fail` otherwise.

As most system-related functions, `DownloadFile` works only under UNIX / Linux. Also the computer must of course be connected to the Internet.

##### 4.6-2 SendEmail

`‣ SendEmail`( sendto, copyto, subject, text ) | ( function )

Returns: zero if everything worked correctly, and a system error number otherwise.

Sends an e-mail with subject subject and body text to the addresses in the list sendto, and copies it to those in the list copyto. The first two arguments must be lists of strings, and the latter two must be strings.

As most system-related functions, `SendEmail` works only under UNIX / Linux. Also the computer must of course be connected to the Internet.

##### 4.6-3 EmailLogFile

`‣ EmailLogFile`( addresses ) | ( function )

Returns: zero if everything worked correctly, and a system error number otherwise.

Sends the current log file by e-mail to addresses, if GAP is in logging mode and one is working under UNIX / Linux, and does nothing otherwise. The argument addresses must be either a list of e-mail addresses or a single e-mail address. Long log files are abbreviated, i.e. if the log file is larger than 64KB, then any output is truncated at 1KB, and if the log file is still longer than 64KB afterwards, it is truncated at 64KB.

#### 4.7 Creating bitmap pictures

ResClasses provides functions to generate bitmap picture files from suitable pixel matrices and vice versa. The author has successfully tested this feature both under Linux and under Windows, and the generated pictures can be processed further with many common graphics programs:

##### 4.7-1 SaveAsBitmapPicture

`‣ SaveAsBitmapPicture`( picture, filename ) | ( function )

Returns: nothing.

Writes the pixel matrix picture to a bitmap- (bmp-) picture file named filename. The filename should include the entire pathname. The argument picture can be a GF(2) matrix, in which case a monochrome picture file is generated. In this case, zeros stand for black pixels and ones stand for white pixels. The argument picture can also be an integer matrix, in which case a 24-bit true color picture file is generated. In this case, the entries of the matrix are supposed to be integers n = 65536 ⋅ red + 256 ⋅ green + blue in the range 0, dots, 2^24-1 specifying the RGB values of the colors of the pixels.

The picture can be read back into GAP by the function `LoadBitmapPicture(filename)`.

    gap> color   := n->32*(n mod 8)+256*32*(Int(n/8) mod 8)+65536*32*Int(n/64);;
    gap> picture := List([1..512],y->List([1..512],x->color(Gcd(x,y)-1)));;
    gap> SaveAsBitmapPicture(picture,Filename(DirectoryTemporary(),"gcd.bmp"));

##### 4.7-2 DrawLineNC

`‣ DrawLineNC`( pic, x1, y1, x2, y2, color, width ) | ( function )

Returns: nothing.

Draws a line on picture pic from (x1,y1) to (x2,y2), with color color and of width width.

    gap> picture := NullMat(100,100)+2^24-1;;
    gap> DrawLineNC(picture,30,20,70,80,255,8);
    gap> SaveAsBitmapPicture(picture,Filename(DirectoryTemporary(),
    >                        "example.bmp"));

#### 4.8 Some general utility functions

ResClasses provides a few small utility functions and -operations which can be used in a more general context. They are described in this section.

There is an operation `PositionsSublist(list,sub)` which returns the list of positions at which sub occurs as a sublist of list.

    gap> PositionsSublist([1,2,6,2,7,2,7,2,3,1,6,2,7,2,8],[2,7,2]);
    [ 4, 6, 12 ]
    gap> PositionsSublist([1,2,3,4,3,2,1],[1,3,5]);
    [  ]
    gap> PositionsSublist("This is an example, isn't it?","is");
    [ 3, 6, 21 ]

Also there are methods `EquivalenceClasses(l,inv)` and `EquivalenceClasses(l,rel)` which decompose a list l into equivalence classes under an equivalence relation. The equivalence relation is given either as a function inv computing a class invariant of a given list entry or as a function rel which takes as arguments two list entries and returns either `true` or `false` depending on whether the arguments belong to the same equivalence class or not.

    gap> EquivalenceClasses([2..50],n->Length(Factors(n)));
    [ [ 2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47 ],
      [ 4, 6, 9, 10, 14, 15, 21, 22, 25, 26, 33, 34, 35, 38, 39, 46, 49 ],
      [ 8, 12, 18, 20, 27, 28, 30, 42, 44, 45, 50 ], [ 16, 24, 36, 40 ],
      [ 32, 48 ] ]
    gap> EquivalenceClasses(AsList(AlternatingGroup(4)),
    >                       function ( g, h )
    >                         return IsConjugate(SymmetricGroup(4),g,h);
    >                       end);
    [ [ (2,3,4), (2,4,3), (1,2,3), (1,2,4), (1,3,2), (1,3,4), (1,4,2),
          (1,4,3) ], [ (1,2)(3,4), (1,3)(2,4), (1,4)(2,3) ], [ () ] ]

Further, there is an operation `GraphClasses(n)` which returns a list of isomorphism classes of graphs with vertices 1, 2, dots, n, and an operation `AllGraphs(n)` which returns a list of representatives of these classes. The graphs are represented as lists of edges, where each edge is a list of the two vertices it connects, and they are ordered by ascending number of edges. Given a graph graph with n vertices, the operation `IdGraphNC(graph,GraphClasses(n))` returns the index `i` such that graph lies in `GraphClasses(n)[i]`. For reasons of efficiency, `IdGraphNC` performs no argument checks.

    gap> GraphClasses(3);
    [ [ [  ] ], [ [ [ 1, 2 ] ], [ [ 2, 3 ] ], [ [ 1, 3 ] ] ],
      [ [ [ 1, 2 ], [ 1, 3 ] ], [ [ 1, 2 ], [ 2, 3 ] ],
          [ [ 1, 3 ], [ 2, 3 ] ] ], [ [ [ 1, 2 ], [ 1, 3 ], [ 2, 3 ] ] ] ]
    gap> List(last,Length); # sizes of classes
    [ 1, 3, 3, 1 ]
    gap> AllGraphs(4);
    [ [  ], [ [ 1, 2 ] ], [ [ 1, 2 ], [ 1, 3 ] ], [ [ 1, 2 ], [ 3, 4 ] ],
      [ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ] ], [ [ 1, 2 ], [ 1, 3 ], [ 2, 3 ] ],
      [ [ 1, 2 ], [ 1, 3 ], [ 2, 4 ] ],
      [ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ], [ 2, 3 ] ],
      [ [ 1, 2 ], [ 1, 3 ], [ 2, 4 ], [ 3, 4 ] ],
      [ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ], [ 2, 3 ], [ 2, 4 ] ],
      [ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ], [ 2, 3 ], [ 2, 4 ], [ 3, 4 ] ] ]
    gap> List(last,Length); # numbers of edges
    [ 0, 1, 2, 2, 3, 3, 3, 4, 4, 5, 6 ]
    gap> IdGraphNC([[1,3],[1,8],[3,8]],GraphClasses(4)); # a triangle graph
    6
    gap> AllGraphs(4)[last];
    [ [ 1, 2 ], [ 1, 3 ], [ 2, 3 ] ]

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

generated by GAPDoc2HTML