<Chapter Label="smallsemi"><Heading>Introduction</Heading>
	
This  manual  describes the <Package>Smallsemi</Package> 
package (Version &VERSION;) for &GAP;.<P/>

The <Package>Smallsemi</Package> 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<Alt Not="Text"> (orders not included in the library are in
italics)</Alt>. The number of semigroups of size 10 is not known at
the time of writing.

<Table Align="|r|r|" Label="nrobjects">
 <HorLine/>
  <Row>
   <Item>Size</Item><Item>Number of semigroups</Item>
  </Row>
 <HorLine/>
 <HorLine/>
 <Row>
   <Item>1</Item><Item>1</Item>
  </Row>
 <HorLine/>
  <Row>
   <Item>2</Item><Item>4</Item>
  </Row>
 <HorLine/>
   <Row>
   <Item>3</Item><Item>18</Item>
  </Row>
 <HorLine/>
   <Row>
   <Item>4</Item><Item>126</Item>
  </Row>
 <HorLine/>
   <Row>
   <Item>5</Item><Item>1 160</Item>
  </Row>
 <HorLine/>
   <Row>
   <Item>6</Item><Item>15 973</Item>
  </Row>
 <HorLine/>
   <Row>
   <Item>7</Item><Item>836 021</Item>
  </Row>
 <HorLine/>
   <Row>
   <Item>8</Item><Item>1 843 120 128</Item>
  </Row>
 <HorLine/>
   <Row>
   <Item>9</Item><Item><E>52 989 400 714 478</E></Item>
  </Row>
 <HorLine/>
</Table>

The initial idea for <Package>Smallsemi</Package> 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 <Package>SmallGroups Library</Package> 
<Cite Key="smallgroups"/> 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.
<P/>

In the remainder of the introduction we explain
what you need to do to install and optimize <Package>Smallsemi</Package>; see 
Subsections <Ref Subsect="reqs"/> and <Ref Subsect="install"/>.  <P/>

In Chapter <Ref Chap="data"/> we 
explain how the semigroups where obtained, what exactly is stored and
how, and which additional properties have been precomputed.  <P/>

The the types of use <Package>Smallsemi</Package> is intended for and its 
limitations are described in Chapter <Ref Chap="examples"/>. 
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. <P/>

Chapter <Ref Chap="small"/> has all the information about available functions. 

<Section Label="reqs"><Heading>Requirements</Heading>

This software is written for &GAP; 4. It requires an existing installation of
&GAP; in version 4.5 or higher. 
<P/>
It is recommended but not necessary to have the &GAP; 4 packages
<Package>Citrus</Package> and <Package>sgpviz</Package> installed as
well. <Package>Citrus</Package> provides a wide range of functionality
for working with semigroups which is not available in the &GAP; core
system while <Package>sgpviz</Package> is recommended for its ability to 
graphically represent small semigroups.
<P/>
<Subsection Label="os"><Heading>Operating System</Heading>
The current version of <Package>Smallsemi</Package> was created for
use under Unix. It will also work under Windows but only if all files
in the directory <F>smallsemi/data</F> and all of its subdirectories
are uncompressed.

See Subsection <Ref Subsect="diskspace"/> for additional comments on
working with <Package>Smallsemi</Package> under Windows.
</Subsection>

<Subsection Label="ram"><Heading>RAM</Heading>
Working with <Package>Smallsemi</Package> 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.
<P/>
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 <Ref Func=
"UnloadSmallsemiData"/> to free memory after every access to the
library. This is likely to slow down computations though. <P/>

For further infomation on how &GAP; uses memory see <Ref Subsect="memory"/> or 
<Ref Sect="Command Line Options" BookName="ref"/>.

</Subsection>

<Subsection Label="diskspace"><Heading>Disk Space</Heading>
As the data in the library is compressed, 30 MB of disk
space will be sufficient to install <Package>Smallsemi</Package> under
Unix.  To use the library under Windows the data has to be
uncompressed and will then occupy approx. 1.6 GB.
<P/>
All data files are compressed using <F>gzip</F>. 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 <E>not</E> currently available under
Windows (or for any other compression type).
<P/>
It should be possible to use <Package>Smallsemi</Package> under
Windows after unzipping all data files. (These are located in
the directory <F>data</F> and its subdirectories and have the file
extension <F>.gz</F>.)
</Subsection>

</Section>

<Section Label="install"><Heading>Installation and Setup</Heading>

<Subsection>
<Heading>Download and Extract <Package>Smallsemi</Package></Heading>

The installation follows standard &GAP; rules as outlined in the 
following two steps; see <Ref Sect="Installing a GAP Package" BookName="ref"/> 
for further details.

<Enum>
<Item> Download one of the archives <F>&ARCHIVENAME;.tar.gz</F> or
<F>&ARCHIVENAME;.tar.bz2</F> from
<Br></Br>
<URL>http://www-groups.mcs.st-andrews.ac.uk/~jamesm/smallsemi.php</URL>
</Item>

<Item> Move the archive inside a <F>pkg</F> directory. This can be
either the main <F>pkg</F> directory in your &GAP; installation or
your personal <F>pkg</F> directory.
</Item>

<Item> Complete the installation by unpacking the archive, e.g. under
Linux type <F>tar -xzf &ARCHIVENAME;.tar.gz</F> at the prompt for the
gzipped <F>tar</F>-archive.
A subdirectory <F>smallsemi</F> will be created inside the <F>pkg</F>
directory.
</Item>
</Enum>

</Subsection>

<Subsection><Heading>Contents</Heading>
In the subdirectory <F>smallsemi</F> you should find the following
files and folders:

<Table Align="ll">
<Row><Item><F>CHANGELOG</F></Item>
<Item>documents changes to previous versions</Item></Row>
<Row><Item><F>data</F></Item>
<Item>contains the data files for semigroups</Item></Row>
<Row><Item><F>doc</F></Item>
<Item>contains the documentation</Item></Row>
<Row><Item><F>gap</F></Item>
<Item>contains the &GAP; code</Item></Row>
<Row><Item><F>LICENSE</F></Item>
<Item>version 3 of the GNU General Public License</Item></Row>
<Row><Item><F>init.g</F></Item>
<Item>implementation file of <Package>Smallsemi</Package></Item></Row>
<Row><Item><F>PackageInfo.g</F></Item>
<Item>meta information about <Package>Smallsemi</Package></Item></Row>
<Row><Item><F>read.g</F></Item>
<Item>declaration file of <Package>Smallsemi</Package></Item></Row>
<Row><Item><F>README.txt</F></Item>
<Item>the README file of <Package>Smallsemi</Package></Item></Row>
<Row><Item><F>tst</F></Item>
<Item>contains test files</Item></Row>
</Table>
<!--General information about the files in a &GAP; package can be found in
<Ref Sect="The Files of a GAP Package" BookName="ext"/>.-->
</Subsection>


<Subsection Label="load"><Heading>Loading</Heading>

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

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

You might want to start &GAP; with a specified amount of memory; see Subsection <Ref Subsect="memory"/>.

</Subsection>

<Subsection Label="memory"><Heading>Memory Issues</Heading>
	
As mentioned in Subsection <Ref Subsect="ram"/>, working with <Package>smallsemi
</Package> can be memory expensive.  It is therefore necessary to either:
<Enum>
<Item>start &GAP; with 1 GB of memory (if possible), for example, by typing 
<C>gap -m 1g</C>; or 
</Item>
<Item>extend the amount memory used by typing <C>return;</C> in the
break-loop whenever &GAP; runs out of memory. For example,
<Log><![CDATA[
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>
]]></Log>
</Item>
</Enum>
</Subsection>

<Subsection><Heading>Testing</Heading>

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

<Log><![CDATA[
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

]]></Log>
</Subsection>

<Subsection><Heading>Customizing</Heading>
If you are using <Package>Smallsemi</Package> regularly you might want
to put the command <C>LoadPackage("smallsemi");</C> into your
<F>.gaprc</F> file; see <Ref Sect="The gap.ini and gaprc files" 
BookName="ref"/>. 
Another option is to save a workspace after
loading <Package>Smallsemi</Package> and executing the following commands
<Log><![CDATA[
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>" );
]]></Log>
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 
<Ref Sect="Saving and Loading a Workspace" BookName="ref"/>.<P/>

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 <Ref Subsect="diskspace"/>
and compress the workspace with gzip to roughly 10 MB.)
</Subsection>
</Section>
</Chapter>
	
