  <Chapter Label="semigroups">
  <Heading>The &Semigroups; package</Heading>
  <Index Key="Semigroups">&Semigroups; package overview</Index>	
    
  <Section><Heading>Introduction</Heading>
    This is the manual for the &Semigroups; package version &VERSION;.
    &Semigroups; &VERSION; is a distant descendant of the  
    <URL Text="Monoid package for GAP 3">
      http://schmidt.nuigalway.ie/monoid/index.html</URL> by Goetz Pfeiffer,
    Steve A. Linton, Edmund F. Robertson, and Nik Ruskuc; and
    the Monoid package for GAP 4 by J. D. Mitchell.<P/>
  
    Many of the operations, methods, properties, and functions described in
    this manual only apply to semigroups of transformations, partial
    permutations, bipartitions, subsemigroups of regular Rees 0-matrix
    semigroups over groups, semigroups of matrices over finite fields, free
    inverse semigroups, and free bands. For the sake of brevity, we have opted
    to say <B>semigroup</B> to describe the aforementioned classes of semigroups.
    <P/>

    &Semigroups; &VERSION; contains more efficient methods than those available
    in the &GAP; library (and in many cases more efficient than any other
    software) for creating semigroups and ideals, calculating their Green's
    structure, size, elements, group of units, minimal ideal, and
    testing membership, finding the inverses of a regular element, and
    factorizing elements over the generators, and many more; see Chapters <Ref
      Chap="create"/>, <Ref Chap="Ideals"/>, and  <Ref Chap="green"/>. There are
    also methods for testing if a semigroup satisfies a particular property,
    such as if it is regular, simple, inverse, completely regular, and a variety
    of further properties; see Chapter <Ref Chap="green"/>. The theory
    behind the main algorithms in &Semigroups; will be described in a
    forthcoming article.
    <P/>

    It is harder for &Semigroups; to compute Green's &L;- and &H;-classes of a
    transformation semigroup. The methods used to compute with Green's &R;-
    and &D;-classes are the most efficient in &Semigroups;.  Thus, if you are
    computing with a transformation semigroup, wherever possible, it is advisable
    to use the commands relating to Green's &R;- or &D;-classes rather than
    those relating to Green's &L;-  or &H;-classes. No such difficulties are
    present when computing with semigroups of partial permutations,
    bipartitions, subsemigroups of a regular Rees 0-matrix semigroup over a
    group, or semigroups of matrices over a finite field.
    <P/>
    
    The methods in &Semigroups; allow the computation of individual Green's
    classes without computing the entire data structure of the underlying
    semigroup; see <Ref Oper="GreensRClassOfElementNC"/>.  It is also possible
    to compute the &R;-classes, the number of elements and test membership
    in a semigroup without computing all the elements; see, for example, <Ref
      Oper="GreensRClasses"/>, <Ref Attr="RClassReps"/>, <Ref
      Func="IteratorOfRClassReps"/>, <Ref Func="IteratorOfRClasses"/>, or <Ref
      Func="NrRClasses"/>.  This may be useful if you want to study a very large
    semigroup where computing all the elements of the semigroup is not feasible.
    <P/>

    There are methods for finding: congruences of certain types of semigroups
    (based on Section 3.5 in <Cite Key="howie"/>), the normalizer of a semigroup
    in a permutation group (as given in <Cite Key="Araujo2010aa"/>), the maximal
    subsemigroups of a finite semigroup (based on  <Cite Key="Graham1968aa"/>),
    smaller degree partial permutation representations (based on <Cite
      Key="Schein1992aa"/>) and the character table of an inverse semigroup.
    There are functions for producing pictures of the Green's structure of a
    semigroup, and for drawing bipartitions; see Sections
    <Ref Sect="Section-Visualising-Semigroup"/> 
    and <Ref Sect="Section-Visualising-Bipartition"/>.
    <P/>

    Several standard examples of semigroups are provided see Section <Ref
      Sect="Examples"/>.  &Semigroups; also provides functions to read and write
    collections of transformations, partial permutations, and bipartitions to a
    file; see <Ref Func="ReadGenerators"/> and <Ref
      Func="WriteGenerators"/>.
    <P/>

    Details of how to create and manipulate semigroups of bipartitions can be
    found in Chapter <Ref Chap="bipartition"/>.
    <P/>
    
    Details of how to create and manipulate semigroups of matrices over a
    finite field can be found in Chapter <Ref Chap="Matrix semigroups"/>.
    <P/>

    There are also functions in &Semigroups; to define and manipulate free
    inverse semigroups and their elements; this part of the package was written
    by Julius Jonu&#353;as; see Chapter <Ref Chap="Free inverse semigroups"/>
    and Section 5.10 in <Cite Key="howie"/> for more details.
    <P/>
    
    &Semigroups; contains functions synonymous to some of those defined in the
    &GAP; library but, for the sake of convenience, they have abbreviated
    names; further details can be found at the appropriate points in the
    later chapters of this manual.
    <P/>
    
    &Semigroups; contains different methods for some &GAP; library functions,
    and so you might notice that &GAP; behaves differently when &Semigroups; is
    loaded.  For more details about semigroups in &GAP; or Green's relations in
    particular, see <Ref Sect="Semigroups" BookName="ref"/> or 
    <Ref Sect="Green's Relations" BookName="ref"/>.
    <P/>

    The &Semigroups; package is written &GAP; code and requires the &Orb; and
    &IO; packages. The &Orb; package is used to efficiently compute components
    of actions, which underpin many of the features of &Semigroups;. The &IO;
    package is used to read and write transformations, partial permutations, and
    bipartitions to a file.
    <P/>

    The &Grape; package must be loaded for the operation <Ref
      Oper="SmallestMultiplicationTable"/> to work, and it must be 
    fully compiled for the following functions to work:
    <List>
      <Item> <Ref Oper="MunnSemigroup"/> </Item>
      <Item> 
        <Ref Oper="MaximalSubsemigroups" Label="for an acting semigroup"/>
      </Item>
      <Item> <Ref Oper="IsIsomorphicSemigroup"/> </Item>
      <Item> <Ref Oper="IsomorphismSemigroups"/>. </Item>
    </List>
    If &Grape; is not available or is not compiled, then &Semigroups; can be
    used as normal with the exception that the functions above will not work.
    <P/>

    The &genss; package is used in one version of the function <Ref
      Oper="Normalizer" Label="for a perm group, semigroup, record"/> but
    nowhere else in &Semigroups;. If &genss; is not available, then &Semigroups;
    can be used as normal with the exception that this function will not work.
    <P/> 
    
    Some further details about semigroups in &GAP; and Green's relations in
    particular, can be found in <Ref Sect="Semigroups" BookName="ref"/> and 
    <Ref Sect="Green's Relations" BookName="ref"/>.
    <P/>

    If you find a bug or an issue with the package, then report this using the
    <URL Text="issue tracker">https://github.com/gap-packages/Semigroups/issues</URL>.
   
  </Section>
  
  <Section Label="install">
    <Heading>Installing the &Semigroups; package</Heading>

    In this section we give a brief description of how to start using
    &Semigroups;.<P/>

    It is assumed that you have a working copy of &GAP; with version number 
    &GAPVERS; or higher. The most up-to-date version of &GAP; and instructions
    on how to install it can be obtained from the main &GAP; webpage
    <URL>http://www.gap-system.org</URL>.<P/>

    The following is a summary of the steps that should lead to a
    successful installation of &Semigroups;:

    <List>
     <Item> ensure that the &IO; package version &IOVERS; or higher is
       available. &IO; must be compiled before &Semigroups; can be loaded.
      </Item>
      
      <Item> ensure that the &Orb; package version &ORBVERS; or higher is
        available. &Orb; and &Semigroups; both perform better if &Orb; is
        compiled. 
      </Item>

      <Item>  
        <B>This step is optional:</B> certain functions in &Semigroups; require
        the &Grape; package to be available and fully compiled; a full list of
        these functions can be found above.  To use these functions make sure
        that the &Grape; package version &GRAPEVERS; or higher is available.  If
        &Grape; is not fully installed (i.e. compiled), then &Semigroups; can be
        used as normal with the exception that the functions listed above will
        not work. 
      </Item>

      <Item> 
        <B>This step is optional:</B> the non-deterministic version of the
        function 
        <Ref Oper="Normalizer" Label="for a perm group, semigroup, record"/>
        requires the &genss; package to be loaded. If you want to use this
        function, then please ensure that the &genss; package version
        &GENSSVERS; or higher is available. 
      </Item>
      
      <Item> download the package archive <F>&ARCHIVENAME;.tar.gz</F> from
        <URL Text="the Semigroups package webpage">https://gap-packages.github.io/Semigroups</URL>.
      </Item>
    
      <Item> unzip and untar the file, this should create a directory called
      <F>&ARCHIVENAME;</F>.</Item>
    
      <Item> 
      locate the <F>pkg</F> directory of your &GAP; directory, which contains
      the directories <F>lib</F>, <F>doc</F> and so on. Move the directory
      <F>&ARCHIVENAME;</F> into the <F>pkg</F> directory.  
      </Item>

      <!--     <Item> to use the functions in &Semigroups; for partial permutations and
        inverse semigroups, you must compile the C part of the package 
        (in the "pkg" directory) by doing:
        <Listing>
<![CDATA[cd semigroups
./configure
make]]></Listing>
    Further information about this step can be found in Section <Ref Sect="Compiling"/>. 
    </Item>-->

    <Item> start &GAP; in the usual way.</Item>
  
    <Item> type <C>LoadPackage("semigroups");</C></Item>
    
    <Item> compile the documentation by using <Ref Func="SemigroupsMakeDoc"/>.
    </Item>

  </List>
  
  <!--    <E><B>Please note that</B> &Semigroups; can only be used to compute with
      semigroups of partial permutations if it has been compiled.  </E><P/>-->

    Presuming that the above steps can be completed successfully you will be 
    running the &Semigroups; package!<P/>

    If you want to check that the package is working correctly, you
    should run some of the tests described in Section <Ref Sect="testing"/>.<P/>

  </Section>

  <!-- <Section Label="Compiling">
    <Heading>Compiling the kernel component of &Semigroups;</Heading>
As of version 0.7, the &Semigroups; package has a &GAP; kernel component in C which
should be compiled. This component contains low-level functions relating to
partial permutations and it is not possible to use these features or any
related features in &Semigroups; without compiling the package. It is possible to
run &Semigroups; without compiling it, but &Semigroups; is limited to computing with
transformation semigroups in this case.<P/>

To compile the GAP kernel component in the 'pkg' directory do:
<Listing>
<![CDATA[cd semigroups
./configure
make]]></Listing><P/>

If you installed the package in another 'pkg' directory than the standard 'pkg'
directory in your &GAP; installation, then you have to do two things. Firstly
during compilation you have to use the option '--with-gaproot=PATH' of the
'configure' script where 'PATH' is a path to the main GAP root directory (if
not given the default '../..' is assumed).<P/>

If you installed &GAP; on several architectures, you must execute the
configure/make step for each of the architectures. You can either do this
immediately after configuring and compiling GAP itself on this architecture, or
alternatively (when using version 4.5 of GAP or newer) set the environment
variable 'CONFIGNAME' to the name of the configuration you used when compiling
GAP before running './configure'.  Note however that your compiler choice and
flags (environment variables 'CC' and 'CFLAGS') need to be chosen to match the
setup of the original GAP compilation. For example you have to specify 32-bit
or 64-bit mode correctly!
</Section> -->

<Section Label="doc"><Heading>Compiling the documentation</Heading>

  To compile the documentation use <Ref Func="SemigroupsMakeDoc"/>. If you want
  to use the help system, it is essential that you compile the documentation. 

  <#Include Label="SemigroupsMakeDoc">

  </Section>
    
  <Section Label="testing"><Heading>Testing the installation</Heading>
    
    In this section we describe how to test that &Semigroups; is working as
    intended.  To test that &Semigroups; is installed correctly use 
    <Ref Func="SemigroupsTestInstall"/> or for more extensive tests use 
    <Ref Func="SemigroupsTestAll"/>. Please note that it will take a few
    seconds for <Ref Func="SemigroupsTestInstall"/> to finish and it may take
    several minutes for <Ref Func="SemigroupsTestAll"/> to finish.<P/>

    If something goes wrong, then please review the instructions in Section <Ref
      Sect="install"/> and ensure that &Semigroups; has been properly installed.
    If you continue having problems, please use the
    <URL Text="issue tracker">https://github.com/gap-packages/Semigroups/issues</URL>
    to report the issues you are having. 

    <#Include Label="SemigroupsTestInstall">
    <#Include Label="SemigroupsTestManualExamples">
    <#Include Label="SemigroupsTestAll">

  </Section>

  <Section><Heading>More information during a computation</Heading>
    <#Include Label="InfoSemigroups">
  </Section>

    <Section><Heading>Reading and writing elements to a file</Heading>
    The functions <Ref Func="ReadGenerators"/> and 
    <Ref Func="WriteGenerators"/> can be used to read or write transformations,
    partial permutations, and bipartitions to a file. 
    <#Include Label="SemigroupsDir">
    <#Include Label="ReadGenerators">
    <#Include Label="WriteGenerators">
    <#Include Label="IteratorFromGeneratorsFile">
  </Section>

</Chapter>
