GAP (RCWA) - Chapter 9: Installation and Auxiliary Functions

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

9 Installation and Auxiliary Functions
9.1 Requirements
9.2 Installation
9.3 Building the manual
9.3-1 RCWABuildManual
9.4 The testing routines
9.4-1 RCWATestInstall
9.4-2 RCWATestAll
9.4-3 RCWATestExamples
9.5 The Info class of the package
9.5-1 InfoRCWA
9.6 Running demonstrations
9.6-1 RunDemonstration
9.7 Utility functions for bitmap pictures
9.7-1 SaveAsBitmapPicture
9.7-2 EncryptIntoBitmapPicture
9.8 Converting GAP logfiles to HTML
9.8-1 Log2HTML
9.9 Some general utility functions

### 9 Installation and Auxiliary Functions

#### 9.1 Requirements

This version of RCWA needs at least GAP 4.7.0, ResClasses 3.4.0, GRAPE 4.3 [Soi06], Polycyclic 2.6 [EN09] and GAPDoc 1.4 [LN11]. With possible exception of the most recent version of ResClasses, all needed packages are already present in an up-to-date standard GAP installation. The RCWA package can be used on all platforms for which GAP is available. It is completely written in the GAP language and does neither contain nor require external binaries. In particular, possible warnings concerning missing binaries issued by other packages when loading RCWA can safely be ignored.

#### 9.2 Installation

Like any other GAP package, RCWA must be installed in the `pkg` subdirectory of the GAP distribution. This is accomplished by extracting the distribution file in this directory. If you have done this, you can load the package as usual via `LoadPackage( "rcwa" );`.

#### 9.3 Building the manual

The following routine is a development tool. As all files it generates are included in the distribution file anyway, users will not need it.

##### 9.3-1 RCWABuildManual

`‣ RCWABuildManual`( ) | ( function )

Returns: nothing.

This function builds the manual of the RCWA 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 systems and requires PDFLaTeX.

#### 9.4 The testing routines

##### 9.4-1 RCWATestInstall

`‣ RCWATestInstall`( ) | ( function )

Returns: nothing.

Performs a nontrivial computation to check whether an installation of RCWA appears to work. Errors, i.e. differences to the correct results of the test computation, are reported. The processed test file is `pkg/rcwa/tst/testinstall.tst`.

##### 9.4-2 RCWATestAll

`‣ RCWATestAll`( ) | ( function )

Returns: nothing.

Runs the full test suite of the RCWA package. Any differences to the supposed results of the test computations are reported. The processed test file is `pkg/rcwa/tst/testall.g`.

Please note that the test suite is a tool for developing. The tests are deliberately very volatile to allow to spot possible problems of any kind also in other packages or in the GAP Library. For this reason you may see reports of differences which simply reflect improved methods in other packages or in the GAP Library (for example an object may already know more of its attributes or properties than it is expected to, or an object may be represented in a better way), or which are caused by changes of the way certain objects are printed, and which are therefore harmless. However if the correct and the actual output look different mathematically or if you see error messages or if GAP crashes, then something went wrong. Also, reports about significantly increased run times of individual commands as well as run times of test files which are much longer than the predicted times shown may indicate a problem.

##### 9.4-3 RCWATestExamples

`‣ RCWATestExamples`( ) | ( function )

Returns: nothing.

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

#### 9.5 The Info class of the package

##### 9.5-1 InfoRCWA

`‣ InfoRCWA` | ( info class )

This is the Info class of the RCWA package. See section Info Functions in the GAP Reference Manual for a description of the Info mechanism. For convenience: `RCWAInfo(`n`)` is a shorthand for `SetInfoLevel(InfoRCWA`,n`)`.

#### 9.6 Running demonstrations

RCWA provides a routine to run demonstrations of its functionality or of other features of GAP. It is intended for being used in talks.

##### 9.6-1 RunDemonstration

`‣ RunDemonstration`( filename ) | ( function )

Returns: nothing.

This function executes the commands in the file named filename. It shows a command and the corresponding output, waits for a keystroke, shows the next command and the corresponding output, waits again for a keystroke, and so on until the end of the file. The demonstration can be stopped by pressing `q`. The function is adapted from the function `Demonstration` in the file `lib/demo.g` of the main GAP distribution.

#### 9.7 Utility functions for bitmap pictures

RCWA provides functions to create 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 produced pictures can be processed further with many common graphics programs:

##### 9.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,"~/images/gcd.bmp");

RCWA also provides functions for steganography in bitmap pictures:

##### 9.7-2 EncryptIntoBitmapPicture

`‣ EncryptIntoBitmapPicture`( picturefile, cleartextfile, passphrase ) | ( function )

`‣ DecryptFromBitmapPicture`( picturefile, cleartextfile, passphrase ) | ( function )

Returns: nothing.

The first function encrypts the contents of the textfile named cleartextfile into the image from the file named picturefile, using the passphrase passphrase. The modified image is written to a file whose name is derived from picturefile by appending the string `-out`.

The second function decrypts an encoded text from the file named picturefile using the passphrase passphrase, and writes the obtained cleartext to a file named cleartextfile.

These steganographic utility functions are designed for security rather than speed, and are intended to be used for texts of the order of magnitude of what one would normally write into the body of an e-mail -- encoding about 100kb into a picture of usual size should be still convenient, while the functions are definitely not suitable for encoding entire backups or the like.

`Info` messages on the progress of the encryption / decryption are given at `InfoLevel` 2 of `InfoRCWA`.

#### 9.8 Converting GAP logfiles to HTML

RCWA provides a routine to convert GAP logfiles to HTML.

##### 9.8-1 Log2HTML

`‣ Log2HTML`( logfilename ) | ( function )

Returns: nothing.

This function converts the GAP logfile logfilename to HTML. The extension of the input file must be `*.log`. The name of the output file is the same as the one of the input file except that the extension `*.log` is replaced by `*.html`. There is a sample CSS file in `rcwa/doc/gaplog.css`, which you can adjust to your taste.

#### 9.9 Some general utility functions

RCWA provides a couple of small utility functions which can be used in a more general context. They are described in this section.

The utility functions for groups and group elements are `GeneratorsAndInverses(G)` which returns a list of generators of G and their inverses, the function `EpimorphismByGenerators(G,H)` which is a shorthand for `GroupHomomorphismByImages(G,H, GeneratorsOfGroup(G),GeneratorsOfGroup(H))` (there is also an `NC` version of this), the function `ListOfPowers(g,exp)` which returns the list `[g,g^2,...,g^exp]` of powers of g, and the function `AllProducts(l,k)` which returns the list of all products of k entries of the list l.

The utility functions for lists are `DifferencesList(l)` and `QuotientsList(l)`, which return the list of differences respectively quotients of consecutive entries of the list l, and the function `FloatQuotientsList(l)`, which returns the list of floating point approximations of the latter.

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.

Yet another utility function is `AssignGlobals(rec)` which takes as argument a record rec and assigns its components to global variables of the same (i.e. the component's) names.

Finally, the function `AllSmoothIntegers(maxp,maxn)` returns a list of all integers less than or equal to maxn which do not have prime divisors exceeding maxp, the function `ExponentOfPrime(n,p)` returns the exponent of the prime p in the prime factorization of n, and the function `LaTeXStringFactorsInt(n)` returns the prime factorization of an integer n as a string in LaTeX format.

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

generated by GAPDoc2HTML