<Chapter Label="small"><Heading>Functionality</Heading>

<Section><Heading>Individual Semigroups</Heading>

<!-- from small.g* -->

The semigroups of sizes 1 to 8 are available up to isomorphism 
and anti-isomorphism in <Package>Smallsemi</Package>.  Every semigroup 
in the library is identified by its size
<M>m</M> and a number <M>n</M> lying between 1 and the number of
semigroups of size <M>m</M> (see Table <Ref Label="nrobjects"/>). We
call the pair <M>(m,n)</M> the <E>ID</E> of the semigroup.
<P/>
In this section we give details about the functions relating to 
individual semigroups in <Package>Smallsemi</Package>. This includes
how to access semigroups in the library and how to identify the
semigroup in the library equivalent to an arbitrary semigroup (of size
1 to 8).
<P/>
If you are interested in the properties of a semigroup in the library
or would like to find all the semigroups satisfying a given set of
properties please see Section <Ref Sect="props"/> or Section <Ref
Sect="enums"/> respectively.<P/>

	<#Include Label="SmallSemigroup">
	<#Include Label="IsSmallSemigroup">
	<#Include Label="IsSmallSemigroupElt">
	<#Include Label="RecoverMultiplicationTable">
	<#Include Label="SemigroupByMultiplicationTableNC">
	<#Include Label="IdSmallSemigroup">
	<#Include Label="EquivalenceSmallSemigroup">
	<#Include Label="InfoSmallsemi">
	<#Include Label="UnloadSmallsemiData">
</Section>

<!-- ############### -->

<Section Label="props"><Heading>Properties of Semigroups</Heading>
		
In this section we detail the &GAP; functions that can be used to determine
whether a small semigroup satisfies a certain property.  Let <A>S</A> be a
semigroup. Then 

<List>
<Item> <A>S</A> is a <E>left zero semigroup</E> if <A>xy=x</A> for all
  <A>x,y</A> in <A>S</A>.</Item>

<Item> <A>S</A> is a <E>right zero semigroup</E> if <A>xy=y</A> for all <A>x,y</A> in <A>S</A>.</Item>
<Item><A>S</A> is <E>commutative</E> if <A>xy=yx</A> for all <A>x,y</A> in <A>S</A>.</Item>
<Item> <A>S</A> is <E>simple</E> if it has no proper two-sided ideals.</Item>
<Item> <A>S</A> is <E>zero simple</E> if the only 2-sided ideals are <A>{0}</A> and <A>S</A>.</Item>
<Item> <A>S</A> is <E>regular</E> if for all <A>x</A> in <A>S</A> there exists <A>y</A> in 
<A>S</A> such that <A>xyx=x</A>.</Item>
<Item> <A>S</A> is <E>completely regular</E> if every element of <A>S</A>  lies in a subgroup. </Item>
<Item> <A>S</A> is an <E>inverse semigroup</E> if every element <A>x</A> in <A>S</A> has a unique semigroup 
inverse, that is, a unique element <A>y</A> such that <A>xyx=x</A> and <A>yxy=y</A>.  </Item>
<Item> <A>S</A> is a <E>Clifford semigroup</E> if it is a regular semigroup whose idempotents are central, 
that is, for all <A>e,x</A> in <A>S</A> where <A>e^2=e</A> we have that <A>ex=xe</A>. </Item>
<Item> <A>S</A> is a <E>band</E> if every element is an idempotent, that is, <A>x^2=x</A> 
for all <A>x</A> in <A>S</A>.</Item>
<Item> <A>S</A> is a <E>Brandt semigroup</E> if it is inverse and zero simple.</Item>
<Item> <A>S</A> is a <E>rectangular band</E> if for all <A>x,y,z</A> in <A>S</A> 
we have that <A>x^2=x</A> and <A>xyz=xz</A>.</Item>
<Item> <A>S</A> is a <E>semiband</E> if it is generated by its idempotent elements, 
that is, elements satisfying <A>x^2=x</A>.</Item>
<Item> <A>S</A> is an <E>orthodox
semigroup</E> if it is regular and its idempotents (elements satisfying <A>x^2=x</A>) 
form a subsemigroup.</Item>
<Item><A>S</A> is a <E>zero semigroup</E> if there exists an element <A>0</A> in 
<A>S</A> such that <A>xy=0</A> for all <A>x,y</A> in <A>S</A>.</Item>
<Item><A>S</A> is a <E>zero group</E> if there exists an element <A>0</A> in 
<A>S</A> such that <A>S</A> without <A>0</A> is a group and for all <A>x</A> in <A>S</A> we have that 
<A>x0=0x=0</A>.</Item>
</List>

		The <Package>MONOID</Package> package was used to determined which semigroups in the library satisfy the properties above. 
		All of the resulting information is stored in the library.

	<#Include Label="Annihilators">
	<#Include Label="DiagonalOfMultiplicationTable">
	<#Include Label="DisplaySmallSemigroup">
	<#Include Label="IndexPeriod">
	<#Include Label="IsBand">
	<#Include Label="IsBrandtSemigroup">
	<#Include Label="IsCliffordSemigroup">
	<#Include Label="IsCommutativeSemigroup">
	<#Include Label="IsCompletelyRegularSemigroup">
	<#Include Label="IsFullTransformationSemigroupCopy">
	<#Include Label="IsGroupAsSemigroup">
	<#Include Label="IsIdempotentGenerated">
	<#Include Label="IsInverseSemigroup">
	<#Include Label="IsLeftZeroSemigroup">
	<#Include Label="IsMonogenicSemigroup">
	<#Include Label="IsMonoidAsSemigroup">
	<#Include Label="IsMultSemigroupOfNearRing">
	<#Include Label="IsNGeneratedSemigroup">
	<#Include Label="IsNIdempotentSemigroup">
	<#Include Label="IsNilpotentSemigroup">
        <#Include Label="IsOrthodoxSemigroup">
	<#Include Label="IsRectangularBand">
	<#Include Label="IsRegularSemigroup">
	<#Include Label="IsRightZeroSemigroup">
	<#Include Label="IsSelfDualSemigroup">
	<#Include Label="IsSemigroupWithClosedIdempotents">
	<#Include Label="IsSemigroupWithZero">
	<#Include Label="IsSimpleSemigroup">
	<#Include Label="IsSingularSemigroupCopy">
	<#Include Label="IsZeroGroup">
	<#Include Label="IsZeroSemigroup">
	<#Include Label="IsZeroSimpleSemigroup">
	<#Include Label="MinimalGeneratingSet">
	<#Include Label="NilpotencyDegree">
</Section>

<Section Label="coclass"><Heading>Nilpotent semigroups by coclass</Heading>

	A useful parameter in the classification of nilpotent semigroups is
        their coclass. For a finite nilpotent semigroup of order <M>n</M> and
        nilpotency degree <M>d</M> the coclass is defined as <M>n-d</M>. In
        <Cite Key="Dis14"/> lists up to (anti-)isomorphism are provided for
        nilpotent semigroups of coclass 0, 1, and 2. The semigroups in the
        lists are given by finite presentations. In this section we describe
        a function that allows to access such lists in &GAP;.
        <P/>
        A further invariant of a nilpotent semigroup <M>S</M> is the size of
        its unique minimal generating set <M>S\backslash S^2</M>. The possible
        sizes for a particular coclass are restricted. Monogenic nilpotent
        semigroups are precisely those of coclass 0. For coclass
        <M>d \geq 1</M> the size of the minimal generating set is at least 2
        and at most <M>d+1</M>.

	<#Include Label="NilpotentSemigroupsByCoclass">

</Section>

<Section Label="star"><Heading>Starred Green's relations</Heading>

	In this section functionality around the starred Green's relations is
        described. The five starred Green's relations are <M>R^*</M>,
        <M>L^*</M>, <M>J^*</M>, <M>H^*</M>, and <M>D^*</M>;
        two elements <M>a</M>, <M>b</M> from a semigroup <M>S</M> are
        <M>R^*</M>-related if for all <M>x, y \in S^1: xa=ya</M> if and only if
        <M>xb = yb</M>; and <M>a</M> and <M>b</M> are <M>L^*</M>-related if 
        for all <M>x, y \in S^1: 
        ax=ay</M> if and only if <M>bx = by</M>. In parallel to the classical
        Green's relations <Ref Sect="Green's Relations" BookName="ref"/>
        <M>H^*=R^* \wedge L^*</M> and 
        <M>D^*= R^* \vee L^*</M> (but <M>R^* \circ L^* = L^* \circ R^*</M>
        does <E>not</E> hold in general). To describe <M>J^*</M> is a bit
        more technical. For <M>a,b \in S</M> one can show that <M>b</M> lies in
        <M>J^*(a)</M>, the principal *-ideal of <M>a</M>, if and only if there
        exist <M>c_0,c_1\ldots,c_n\in S</M> and <M>x_1,\ldots,x_n,y_1,\ldots,
        y_n\in S^1</M> such that <M>a=c_0, b=c_n</M> and 
        <M>c_iD^*x_ic_{i-1}y_i</M> for <M>1\leq i\leq n</M>. Then <M>aJ^*b</M>
        if and only if both <M>a\in J^*(b)</M> and <M>b\in J^*(a)</M>
        <P/> 

        Note that even for finite semigroups <M>J^*</M> does not always equal
        <M>D^*</M> (in contrast to the situation for classical Green's 
        relations). Using <Package>Smallsemi</Package> it was shown that there
        exist semigroups of order 8 with <M>J^*\neq D^*</M> 
        <Cite Key="DMU13"/>. 

	<#Include Label="IsStarRelation">
	<#Include Label="RStarRelation">
	<#Include Label="RStarClassOperation">
	<#Include Label="RStarClassAttribute">
	<#Include Label="IsStarClass">
	<#Include Label="RStarClasses">
</Section>

<Section Label="enums"><Heading>Families of Semigroups</Heading>
	
	In this section we describe how to find semigroups in the library satisfying a given set of 
	parameters.<P/>
	
	The following functions have the same usage but may return different 
	values:  <Ref Func="EnumeratorOfSmallSemigroups"/>, <Ref Func="AllSmallSemigroups"/>, 
	<Ref Func="EnumeratorSortedOfSmallSemigroups"/>, <Ref Func="IdsOfSmallSemigroups"/>, 
	<Ref Func="IteratorOfSmallSemigroups"/>, <Ref Func="NrSmallSemigroups"/>, 
	<Ref Func="OneSmallSemigroup"/>, <Ref Func="PositionsOfSmallSemigroups"/>, 
	<Ref Func="RandomSmallSemigroup"/>. <P/>
	
	The number of arguments should be odd: 
	<List>
	<Item>the first argument <C>arg[1]</C> should be a positive integer, a list of positive integers, or 
	an enumerator or iterator of small semigroups satisfying <Ref Func="IsEnumeratorOfSmallSemigroups"/> or 
	<Ref Func="IsIteratorOfSmallSemigroups"/></Item> 
	<Item> the even arguments <C>arg[2i]</C>, if present, should be a function</Item> 
	<Item> the odd arguments <C>arg[2i+1]</C> argument should be a possible value that can be returned by the function
	<C>arg[2i]</C>.</Item>
	</List>
	
	In the case that the function is <Ref Func="AllSmallSemigroups"/> and <C>arg[1]</C> is a positive integer, then 
	the returned value is a list of all semigroups <M>S</M> with <C>arg[1]</C> 
	elements such that <C>arg[2i](S)=arg[2i+1]</C>.<P/>
	
	For example, to obtain all the commutative semigroups with <A>3</A> idempotents of 
	sizes <A>2</A> to <A>5</A> use one of <Ref Func="EnumeratorOfSmallSemigroups"/>, <Ref Func="AllSmallSemigroups"/>, 
	<Ref Func="EnumeratorSortedOfSmallSemigroups"/>, <Ref Func="IteratorOfSmallSemigroups"/> with argument
	<Log>
[2..5], IsCommutative, true, Is3IdempotentGenerated, true
	</Log>
	<Ref Func="AllSmallSemigroups"/> returns a list of all such semigroups, <Ref Func="EnumeratorOfSmallSemigroups"/>, 
	<Ref Func="EnumeratorSortedOfSmallSemigroups"/>, and  
	<Ref Func="IteratorOfSmallSemigroups"/> return an enumerator and an iterator of all such semigroups, respectively. 
	For more information on enumerators and iterators see <Ref Attr="Enumerator" BookName="ref"/>, 
	<Ref Attr="EnumeratorSorted" BookName="ref"/>, or <Ref Oper="Iterator" BookName="ref"/>. The following are
	rules of thumb regarding the different situations when these functions should be used in order of slowest to fastest and greatest 
	memory use to least:
	<List>
	<Item><Ref Func="AllSmallSemigroups"/> should be used if the number of semigroups is not too large and you want to keep the 
	created semigroups in a list. 
	</Item>
	<Item><Ref Func="EnumeratorOfSmallSemigroups"/> or <Ref Func="EnumeratorSortedOfSmallSemigroups"/> should be used when 
	the functions in even indexed positions are those stored in the library (see <Ref Var="PrecomputedSmallSemisInfo"/>) or you want 
	repeatedly search the same set of semigroups and there are too many to store in a list.  Note that the enumerator stores the 
	id numbers of its elements but not the semigroups themselves. Hence every time an element of the 
	enumerator is required it must be recreated from the multiplication table data.
		</Item>
	<Item><Ref Func="IteratorOfSmallSemigroups"/> should be used if the functions in even indexed positions are not stored in the
	library (see <Ref Var="PrecomputedSmallSemisInfo"/>) or if you just want to run through all the semigroups satisfying the specified 
	parameters once only. Note that each new call of <Ref Func="IteratorOfSmallSemigroups"/> requires &GAP; to recompute its elements 
	which may be slow if the functions are user-defined or not stored in the library.</Item>
	</List>
	Further information on the 
	relative virtues of these different commands can be found in Chapter <Ref Chap="examples"/>.<P/> 
	
	As a further example, if we want to obtain a single non-simple semigroup with <M>7</M> elements and trivial automorphism group, 
	then we would use one of the functions <Ref Func="OneSmallSemigroup"/> or <Ref Func="RandomSmallSemigroup"/> with argument<P/>
	<Log>
7, IsSimpleSemigroup, false, x-> IsTrivial(AutomorphismGroup(x)), true
	</Log>
	<Ref Func="OneSmallSemigroup"/> should return an answer more quickly than <Ref Func="RandomSmallSemigroup"/>. Also note that 
	<Ref Func="OneSmallSemigroup"/> will always return the same semigroup, i.e. the first semigroup in the library with the given 
	parameters. 
	
	<#Include Label="AllSmallSemigroups">
	<#Include Label="EnumeratorOfSmallSemigroups">
	<#Include Label="EnumeratorOfSmallSemigroupsByIds">
	<#Include Label="EnumeratorSortedOfSmallSemigroups">
	<#Include Label="FuncsOfSmallSemisInEnum">
	<#Include Label="FuncsOfSmallSemisInIter">
	<#Include Label="IdsOfSmallSemigroups">
	<#Include Label="IsEnumeratorOfSmallSemigroups">
	<#Include Label="IsIdSmallSemigroup">
	<#Include Label="IsIteratorOfSmallSemigroups">
	<#Include Label="IteratorOfSmallSemigroups">
	<#Include Label="NamesFuncsSmallSemisInEnum">
	<#Include Label="NamesFuncsSmallSemisInIter">
	<#Include Label="Nr3NilpotentSemigroups">
	<#Include Label="NrSmallSemigroups">
	<#Include Label="OneSmallSemigroup">
	<#Include Label="PositionsOfSmallSemigroups">
	<#Include Label="PositionsOfSmallSemisInEnum">
	<#Include Label="PrecomputedSmallSemisInfo">
	<#Include Label="RandomSmallSemigroup">
	<#Include Label="SizesOfSmallSemisInEnum">
	<#Include Label="SizesOfSmallSemisInIter">
	<#Include Label="UpToIsomorphism">
	
</Section>
</Chapter>
