[MathJax off]

1 Introduction

This manual describes the Smallsemi package (Version 0.7.1) 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.

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 information 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.7.1.tar.gz or smallsemi-0.7.1.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.7.1.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:

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 & James Mitchell
For contents, type: ?Smallsemi:
Loading Smallsemi &VERSION; ...
-----------------------------------------------------------------------------
true

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

generated by GAPDoc2HTML