GAP (Smallsemi) - Chapter 1: Introduction

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

[MathJax off]

1 Introduction
1.1 Requirements
1.1-1 Operating System
1.1-2 RAM
1.1-3 Disk Space
1.2 Installation and Setup
1.2-1 Download and Extract Smallsemi
1.2-2 Contents
1.2-3 Loading
1.2-4 Memory Issues
1.2-5 Testing
1.2-6 Customizing

### 1 Introduction

This manual describes the Smallsemi package (Version 0.6.13) for GAP.

The Smallsemi package is a data library of semigroups of small size. It provides all semigroups with at most 8 elements as well as various information about these objects. The reason that semigroups of higher orders are not included is the huge number of such objects. The numbers of semigroups of sizes 1 to 9 are given in the table below (orders not included in the library are in italics). The number of semigroups of size 10 is not known at the time of writing.

Size | Number of semigroups
1 | 1
2 | 4
3 | 18
4 | 126
5 | 1 160
6 | 15 973
7 | 836 021
8 | 1 843 120 128
9 | 52 989 400 714 478

The initial idea for Smallsemi was developed out of the wish for an extensive number of examples of semigroups of moderate size. This lead to the idea of an electronical database. As an existing example the SmallGroups Library [BEO02] was an inspiration on how such a project could be established. Unfortunately the number of semigroups is so much bigger, and most of them bare so little structure, that new techniques to store and handle the semigroups had to be developed. Of course, the first step was to actually construct all the semigroups.

In the remainder of the introduction we explain what you need to do to install and optimize Smallsemi; see Subsections 1.1 and 1.2.

In Chapter 2 we explain how the semigroups where obtained, what exactly is stored and how, and which additional properties have been precomputed.

The the types of use Smallsemi is intended for and its limitations are described in Chapter 3. The extensive examples can be used as a quick-start guide and as something to come back to after reading the technical details about available functionality in the subsequent sections.

Chapter 4 has all the information about available functions.

#### 1.1 Requirements

This software is written for GAP 4. It requires an existing installation of GAP in version 4.5 or higher.

It is recommended but not necessary to have the GAP 4 packages Citrus and sgpviz installed as well. Citrus provides a wide range of functionality for working with semigroups which is not available in the GAP core system while sgpviz is recommended for its ability to graphically represent small semigroups.

##### 1.1-1 Operating System

The current version of Smallsemi was created for use under Unix. It will also work under Windows but only if all files in the directory `smallsemi/data` and all of its subdirectories are uncompressed. See Subsection 1.1-3 for additional comments on working with Smallsemi under Windows.

##### 1.1-2 RAM

Working with Smallsemi can be memory expensive. We recommend to have at least 1 GB of RAM available. With less than 512 MB not all the semigroups of size 8 can be accessed.

You should be able to use the semigroups of orders 1 through 7 having 128 MB of RAM only. If you have a system with little memory or want to use as little memory as possible for the GAP process try using `UnloadSmallsemiData` (4.1-9) to free memory after every access to the library. This is likely to slow down computations though.

For further infomation on how GAP uses memory see 1.2-4 or Reference: Command Line Options.

##### 1.1-3 Disk Space

As the data in the library is compressed, 30 MB of disk space will be sufficient to install Smallsemi under Unix. To use the library under Windows the data has to be uncompressed and will then occupy approx. 1.6 GB.

All data files are compressed using `gzip`. Under Unix GAP can access the original contents of a gzipped file without uncompressing it as a whole by using a pipe. On 32-bit systems this might fail in extreme circumstances. In that case GAP has to be restarted. This functionality is not currently available under Windows (or for any other compression type).

It should be possible to use Smallsemi under Windows after unzipping all data files. (These are located in the directory `data` and its subdirectories and have the file extension `.gz`.)

#### 1.2 Installation and Setup

##### 1.2-1 Download and Extract Smallsemi

The installation follows standard GAP rules as outlined in the following two steps; see Reference: Installing a GAP Package for further details.

1. Download one of the archives `smallsemi-0.6.13.tar.gz` or `smallsemi-0.6.13.tar.bz2` from
   http://www-groups.mcs.st-andrews.ac.uk/~jamesm/smallsemi.php

2. Move the archive inside a `pkg` directory. This can be either the main `pkg` directory in your GAP installation or your personal `pkg` directory.

3. Complete the installation by unpacking the archive, e.g. under Linux type `tar -xzf smallsemi-0.6.13.tar.gz` at the prompt for the gzipped `tar`-archive. A subdirectory `smallsemi` will be created inside the `pkg` directory.

##### 1.2-2 Contents

In the subdirectory `smallsemi` you should find the following files and folders:

`CHANGELOG` | documents changes to previous versions
`data` | contains the data files for semigroups
`doc` | contains the documentation
`gap` | contains the GAP code
`LICENSE` | version 3 of the GNU General Public License
`init.g` | implementation file of Smallsemi
`PackageInfo.g` | meta information about Smallsemi
`read.g` | declaration file of Smallsemi
`README.txt` | the README file of Smallsemi
`tst` | contains test files

##### 1.2-3 Loading

To use the package, start a GAP session and type `LoadPackage("smallsemi");` at the GAP prompt. You should see the following:

    gap> LoadPackage("smallsemi");
    -----------------------------------------------------------------------------
    Smallsemi - A library of small semigroups
    by Andreas Distler &amp; James Mitchell
    For contents, type: ?Smallsemi:
    Loading Smallsemi &VERSION; ...
    -----------------------------------------------------------------------------
    true
    gap>

You might want to start GAP with a specified amount of memory; see Subsection 1.2-4.

##### 1.2-4 Memory Issues

As mentioned in Subsection 1.1-2, working with smallsemi can be memory expensive. It is therefore necessary to either:

1. start GAP with 1 GB of memory (if possible), for example, by typing `gap -m 1g`; or

2. extend the amount memory used by typing `return;` in the break-loop whenever GAP runs out of memory. For example,

       gap> s:=SmallSemigroup(8, 183244314);
       #I  Loading 'smallsemi' data. Please be patient.
       #I  Loading 'smallsemi' data.
       Error, exceeded the permitted memory (`-o' command line option)
       SplitString( StringFile( file ), "\n" ) called from
       READ_3NIL_DATA( diag ); called from
       RecoverMultiplicationTable( size, nr ) called from
       <function>( <arguments> ) called from read-eval-loop
       you can 'return;'
       brk>

##### 1.2-5 Testing

You should verify the success of the installation by running the test file. This is done by the following command and should return a similar output (the timings will differ depending on the speed of your machine):

    gap> ReadPackage( "smallsemi", "tst/testall.g" );
    Architecture: aarch64-apple-darwin21.3.0-default64-kv8

    testing: smallsemi/tst/coclass.tst
        2350 ms (323 ms GC) and 471MB allocated for coclass.tst
    testing: smallsemi/tst/enums.tst
        3452 ms (923 ms GC) and 2.69GB allocated for enums.tst
    testing: smallsemi/tst/greensstar.tst
         173 ms (109 ms GC) and 90.1MB allocated for greensstar.tst
    testing: smallsemi/tst/properties.tst
         574 ms (233 ms GC) and 213MB allocated for properties.tst
    testing: smallsemi/tst/small.tst
         322 ms (201 ms GC) and 174MB allocated for small.tst
    testing: smallsemi/tst/smallsemi01.tst
         323 ms (56 ms GC) and 128MB allocated for smallsemi01.tst
    testing: smallsemi/tst/smallsemi02.tst
        2079 ms (587 ms GC) and 1.23GB allocated for smallsemi02.tst
    -----------------------------------
    total      9273 ms (2432 ms GC) and 4.98GB allocated
                  0 failures in 7 files

    #I  No errors detected while testing

##### 1.2-6 Customizing

If you are using Smallsemi regularly you might want to put the command `LoadPackage("smallsemi");` into your `.gaprc` file; see Reference: The gap.ini and gaprc files. Another option is to save a workspace after loading Smallsemi and executing the following commands

    gap> SmallSemigroup(7,1);; MOREDATA2TO8;;
    #I  smallsemi: loading data for semigroups of size 7.
    #I  smallsemi: loading data for semigroup properties. Please be patient.
    gap> SaveWorkspace( "<filename for the workspace>" );

Doing this will mean that it is not necessary to load the data from the library every time you start a new GAP session; see Reference: Saving and Loading a Workspace.

The size of the file containing the saved workspace will be around 76 MB. Loading this workspace is much quicker than starting a new GAP session and all the data for semigroups of orders 1 through 7 is immediately available. (If you are working under Unix you can make use of the functionality mentioned in Subsection 1.1-3 and compress the workspace with gzip to roughly 10 MB.)

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

generated by GAPDoc2HTML