#############################################################################
##
#W  examples.xml
#Y  Copyright (C) 2011-14                                James D. Mitchell
##
##  Licensing information can be found in the README file of this package.
##
#############################################################################
##

<#GAPDoc Label="EndomorphismsPartition">
   <ManSection>
    <Oper Name="EndomorphismsPartition" Arg="list"/>
    <Returns>A transformation monoid.</Returns>
    <Description>
      If <A>list</A> is a list of positive integers, then 
      <C>EndomorphismsPartition</C> returns a monoid of endomorphisms preserving
      a partition of <C>[1..Sum(<A>list</A>)]</C> with
      a part of length <C><A>list</A>[i]</C> for
      every <C>i</C>. For example, if <C><A>list</A>=[1,2,3]</C>, then
      <C>EndomorphismsPartition</C> returns the monoid of endomorphisms of the
      partition <C>[[1],[2,3],[4,5,6]]</C>. <P/>
      
      If <C>f</C> is a transformation of <C>[1..n]</C>, then it is an
      <B>endomorphism</B> of a partition <C>P</C> on <C>[1..n]</C> if
      <C>(i,j)</C> in <C>P</C> implies that <C>(i^f, j^f)</C> is in <C>P</C>. <P/>

      <C>EndomorphismsPartition</C> returns a monoid with a minimal size
      generating set, as described in <Cite Key="Araujo2014aa"/>.

      <Example><![CDATA[
gap> S:=EndomorphismsPartition([3,3,3]);
<transformation semigroup of degree 9 with 4 generators>
gap> Size(S);
531441
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="JonesMonoid">
   <ManSection>
    <Oper Name="JonesMonoid" Arg="n"/>
    <Oper Name="TemperleyLiebMonoid" Arg="n"/>
    <Oper Name="SingularJonesMonoid" Arg="n"/>
    <Returns>A bipartition monoid.</Returns>
    <Description>
      If <A>n</A> is a positive integer, then this operation returns the Jones
      monoid of degree <A>n</A>. The <B>Jones monoid</B> is the subsemigroup of
      the Brauer monoid consisting of those bipartitions with a planar diagram.
      The Jones monoid is sometimes referred to as the <B>Temperley-Lieb
        monoid</B>. <P/>

      <C>SingularJonesMonoid</C> returns the ideal of the Jones monoid
      consisting of the non-invertible elements (i.e. those not in the group of
      units), when <A>n</A> is at least 2.  

      <Example><![CDATA[
gap> S:=JonesMonoid(4);
<regular bipartition monoid of degree 4 with 3 generators>
gap> SingularJonesMonoid(8);
<regular bipartition semigroup ideal of degree 8 with 1 generator>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="BrauerMonoid">
   <ManSection>
    <Oper Name="BrauerMonoid" Arg="n"/>
    <Oper Name="SingularBrauerMonoid" Arg="n"/>
    <Returns>A bipartition monoid.</Returns>
    <Description>
      If <A>n</A> is a positive integer, then this operation returns the Brauer
      monoid of degree <A>n</A>. The <B>Brauer monoid</B> is the subsemigroup of
      the partition monoid consisiting of those bipartitions where the size of
      every block is 2. <P/>
      
      <C>SingularBrauerMonoid</C> returns the ideal of the Brauer monoid
      consisting of the non-invertible elements (i.e. those not in the group of
      units), when <A>n</A> is at least 2. 

      <Example><![CDATA[
gap> S:=BrauerMonoid(4);
<regular bipartition monoid of degree 4 with 3 generators>
gap> IsSubsemigroup(S, JonesMonoid(4));
true
gap> Size(S);
105
gap> SingularBrauerMonoid(8);
<regular bipartition semigroup ideal of degree 8 with 1 generator>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="PartitionMonoid">
   <ManSection>
    <Oper Name="PartitionMonoid" Arg="n"/>
    <Oper Name="SingularPartitionMonoid" Arg="n"/>
    <Returns>A bipartition monoid.</Returns>
    <Description>
      If <A>n</A> is a positive integer, then this operation returns the
      partition monoid of degree <A>n</A> which is the monoid consisting of all
      the bipartitions of degree <A>n</A>. <P/>

      <C>SingularPartitionMonoid</C> returns the ideal of the
      partition monoid consisting of the non-invertible elements
      (i.e. those not in the group of units). <P/>

      <Example><![CDATA[
gap> S:=PartitionMonoid(5);
<regular bipartition monoid of degree 5 with 4 generators>
gap> Size(S);
115975
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="PlanarPartitionMonoid">
   <ManSection>
    <Oper Name="PlanarPartitionMonoid" Arg="n"/>
    <Oper Name="SingularPlanarPartitionMonoid" Arg="n"/>
    <Returns>A bipartition monoid.</Returns>
    <Description>
      If <A>n</A> is a positive integer, then this operation returns the planar
      partition monoid of degree <A>n</A> which is the monoid consisting of all
      the planar bipartitions of degree <A>n</A> (planar bipartitions are defined
      in Chapter <Ref Label="bipartition"/>). <P/>

      <C>SingularPlanarPartitionMonoid</C> returns the ideal of the planar
      partition monoid consisting of the non-invertible elements
      (i.e. those not in the group of units). <P/>

      <Example><![CDATA[
gap> S := PlanarPartitionMonoid(5);
<regular bipartition monoid of degree 5 with 9 generators>
gap> Size(S);
16796
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="PartialTransformationSemigroup">
   <ManSection>
    <Oper Name="PartialTransformationSemigroup" Arg="n"/>
    <Returns>A transformation monoid.</Returns>
    <Description>
      If <A>n</A> is a positive integer, then this function returns a
      semigroup of transformations on <C><A>n</A>+1</C> points which is
      isomorphic to the semigroup consisting of all partial transformation on
      <A>n</A> points. This monoid has <C>(<A>n</A>+1)^<A>n</A></C> elements.
      <!--JDM add generators-->
      <Example><![CDATA[
gap> PartialTransformationSemigroup(8); 
<regular transformation monoid of degree 9 with 4 generators>
gap> Size(last);
43046721]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="UniformBlockBijectionMonoid">
   <ManSection>
    <Oper Name="UniformBlockBijectionMonoid" Arg="n"/>
    <Oper Name="FactorisableDualSymmetricInverseSemigroup" Arg="n"/>
    <Oper Name="SingularUniformBlockBijectionMonoid" Arg="n"/>
    <Oper Name="SingularFactorisableDualSymmetricInverseSemigroup" Arg="n"/>
    <Oper Name="PlanarUniformBlockBijectionMonoid" Arg="n"/>
    <Oper Name="SingularPlanarUniformBlockBijectionMonoid" Arg="n"/>
    <Returns>An inverse bipartition monoid.</Returns>
    <Description>
      If <A>n</A> is a positive integer, then this operation returns the uniform
      block bijection monoid of degree <A>n</A>. The <E>uniform block bijection
      monoid</E> is the submonoid of the partition monoid consisting of the
      block bijections of degree &n; where the number of positive integers in a
      block equals the number of negative integers in that block. 
      The uniform block bijection monoid is also referred to as the 
      <E>factorisable dual symmetric inverse semigroup</E>. <P/>

      <C>SingularUniformBlockBijectionMonoid</C> returns the ideal of the
      uniform block bijection monoid consisting of the non-invertible elements
      (i.e. those not in the group of units), when <A>n</A> is at least 2. <P/>

      <C>PlanarUniformBlockBijectionMonoid</C> returns the submonoid of the
      uniform block bijection monoid consisting of the planar elements
      (i.e. those in the planar partition monoid). <P/>

      <C>SingularPlanarUniformBlockBijectionMonoid</C> returns the ideal of the
      planar uniform block bijection monoid consisting of the non-invertible
      elements (i.e. those not in the group of units), when <A>n</A> is
      at least 2. <P/>
      <!-- TODO reference -->

      See <Ref Prop="IsUniformBlockBijection"/>.       
      <Example><![CDATA[
gap> S := UniformBlockBijectionMonoid(4);
<inverse bipartition monoid of degree 4 with 3 generators>
gap> Size(PlanarUniformBlockBijectionMonoid(8));
128
gap> S:=DualSymmetricInverseMonoid(4);
<inverse bipartition monoid of degree 4 with 3 generators>
gap> IsFactorisableSemigroup(S);
false
gap> S:=FactorisableDualSymmetricInverseSemigroup(4);
<inverse bipartition monoid of degree 4 with 3 generators>
gap> IsFactorisableSemigroup(S);
true
gap> S:=Range(IsomorphismBipartitionSemigroup(SymmetricInverseMonoid(5)));
<inverse bipartition monoid of degree 5 with 3 generators>
gap> IsFactorisableSemigroup(S);
true]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="DualSymmetricInverseSemigroup">
   <ManSection>
    <Oper Name="DualSymmetricInverseSemigroup" Arg="n"/>
    <Oper Name="DualSymmetricInverseMonoid" Arg="n"/>
    <Oper Name="SingularDualSymmetricInverseSemigroup" Arg="n"/>
    <Returns>An inverse bipartition monoid.</Returns>
    <Description>
      If <A>n</A> is a positive integer, then these operations return the dual
      symmetric inverse monoid of degree <A>n</A>, which is the subsemigroup of
      the partition monoid consisting of the block bijections of degree <A>n</A>.<P/>

      <C>SingularDualSymmetricInverseSemigroup</C> returns the ideal of the
      dual symmetric inverse monoid consisting of the non-invertible elements
      (i.e. those not in the group of units), when <A>n</A> is at least 2.<P/>
      
      See <Ref Prop="IsBlockBijection"/>.

      <Example><![CDATA[
gap> Number(PartitionMonoid(3), IsBlockBijection);
25
gap> S := DualSymmetricInverseSemigroup(3);
<inverse bipartition monoid of degree 3 with 3 generators>
gap> Size(S);
25
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="ApsisMonoid">
   <ManSection>
    <Oper Name="ApsisMonoid" Arg="m, n"/>
    <Oper Name="SingularApsisMonoid" Arg="m, n"/>
    <Oper Name="CrossedApsisMonoid" Arg="m, n"/>
    <Oper Name="SingularCrossedApsisMonoid" Arg="m, n"/>
    <Returns>A bipartition monoid.</Returns>
    <Description>
      If <A>m</A> and <A>n</A> are positive integers, then this operation
      returns the <A>m</A>-apsis monoid of degree <A>n</A>. The
      <A>m</A><E>-apsis monoid</E> is the monoid of bipartitions generated when
      the diapses in generators of the Jones monoid are replaced
      with <A>m</A>-apses. Note that an <A>m</A><E>-apsis</E> is a block that 
      contains precisely <A>m</A> consecutive integers. <P/>

      <C>SingularApsisMonoid</C> returns the ideal of the
      apsis monoid consisting of the non-invertible elements
      (i.e. those not in the group of units), when <A>m &lt;= n</A>. <P/>

      <C>CrossedApsisGeneratedMonoid</C> returns the semigroup generated by the
      symmetric group of degree <A>n</A> and the <A>m</A>-apsis monoid of
      degree <A>n</A>. <P/>

      <C>SingularCrossedApsisMonoid</C> returns the ideal of the
      crossed apsis monoid consisting of the non-invertible elements
      (i.e. those not in the group of units), when <A>m &lt;= n</A>.
      <!-- TODO reference and/or definition -->

      <Example><![CDATA[
gap> S := ApsisMonoid(3, 7);
<regular bipartition monoid of degree 7 with 5 generators>
gap> Size(S);
320
gap> Size(CrossedApsisMonoid(4, 9));
24291981]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="ModularPartitionMonoid">
   <ManSection>
    <Oper Name="ModularPartitionMonoid" Arg="m, n"/>
    <Oper Name="SingularModularPartitionMonoid" Arg="m, n"/>
    <Oper Name="PlanarModularPartitionMonoid" Arg="m, n"/>
    <Oper Name="SingularPlanarModularPartitionMonoid" Arg="m, n"/>
    <Returns>A bipartition monoid.</Returns>
    <Description>
      If <A>m</A> and <A>n</A> are positive integers, then this operation
      returns the modular-<A>m</A> partition monoid of degree <A>n</A>. The
      <E>modular-</E><A>m</A> <E>partition monoid</E> is the submonoid of the
      partition monoid such that the numbers of positive and negative
      integers contained in each block are congruent mod <A>m</A>. <P/>

      <C>SingularModularPartitionMonoid</C> returns the ideal of the
      modular partition monoid consisting of the non-invertible elements
      (i.e. those not in the group of units), when either
      <A>m = n = 1</A> or <A>m, n &gt; 1</A>. <P/>

      <C>PlanarModularPartitionMonoid</C> returns the submonoid of the
      modular-<A>m</A> partition monoid consisting of the planar elements
      (i.e. those in the planar partition monoid). <P/>

      <C>SingularPlanarModularPartitionMonoid</C> returns the ideal of the
      planar modular partition monoid consisting of the non-invertible elements
      (i.e. those not in the group of units), when either
      <A>m = n = 1</A> or <A>m, n &gt; 1</A>.
      <!-- TODO reference -->

      <Example><![CDATA[
gap> S := ModularPartitionMonoid(3, 7);
<regular bipartition monoid of degree 7 with 4 generators>
gap> Size(S);
826897
gap> Size(PlanarModularPartitionMonoid(4, 9));
1795]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="GeneralLinearSemigroup">
   <ManSection>
    <Oper Name="FullMatrixSemigroup" Arg="d, q"/>
    <Oper Name="GeneralLinearSemigroup" Arg="d, q"/>
    <Oper Name="GLS" Arg="d, q"/>
    <Returns>A matrix semigroup.</Returns>
    <Description>
      <C>FullMatrixSemigroup</C>, <C>GeneralLinearSemigroup</C>, and <C>GLS</C>
      are synonyms for each other. They both return the full matrix semigroup,
      or if you prefer the general linear semigroup, of <A>d</A> by <A>d</A>
      matrices with entries over the field with <A>q</A> elements.  This
      semigroup has <C><A>q</A> ^ (<A>d</A> ^ 2)</C> elements.
      <P/>

      <Example><![CDATA[
gap> S := FullMatrixSemigroup(3, 4);
<general linear monoid 3x3 over GF(2^2)>
gap> Size(S);
262144]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="SpecialLinearSemigroup">
<ManSection>
  <!--<Oper Name="GeneralLinearSemigroup" Arg="d, q"/>
  <Oper Name="GeneralUnitarySemigroup" Arg="d, q"/>
  <Oper Name="SpecialUnitarySemigroup" Arg="d, q"/>
  <Oper Name="SymplecticSemigroup" Arg="d, q"/>
  <Oper Name="GeneralOrthogonalSemigroup" Arg="d, q"/>
  <Oper Name="SpecialOrthogonalSemigroup" Arg="d, q"/>
  <Oper Name="OmegaSemigroupSemigroup" Arg="d, q"/>
  <Oper Name="ProjectiveOmegaSemigroup" Arg="d, q"/>
  <Oper Name="SpecialSemilinearSemigroup" Arg="d, q"/>
  <Oper Name="GeneralSemilinearSemigroup" Arg="d, q"/>-->
  <Oper Name="SpecialLinearSemigroup" Arg="d, q"/>
  <Oper Name="SLS" Arg="d, q"/>
  <Returns>A matrix semigroup.</Returns>
    <Description>
      <C>SpecialLinearSemigroup</C> and <C>SLS</C> are synonymous.

      The special linear semigroup of <A>d</A> by <A>d</A> matrices
      with entries over the field with <A>q</A> elements is generated
      by a generating set for the special linear group of <A>d</A> by
      <A>d</A> matrices over the field with <A>q</A> elements and a
      matrix of rank <A>d-1</A>.
      <P/><!--FIXME this is not very descriptive-->

      <Example><![CDATA[
gap> S := SLS(3,4);
<special linear monoid 3x3 over GF(2^2)>
gap> Size(S);
141184]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="MunnSemigroup">
    <ManSection>
      <Oper Name="MunnSemigroup" Arg="S"/>
      <Returns>The Munn semigroup of a semilattice.</Returns>
      <Description>
        If <A>S</A> is a semilattice, then <C>MunnSemigroup</C> returns the
        inverse semigroup of partial permutations of isomorphisms of principal
        ideals of <A>S</A>; called the <E>Munn semigroup</E> of <A>S</A>.<P/> 

        This function was written jointly by J. D. Mitchell, Yann Peresse 
        (St Andrews), Yanhui Wang (York). <P/>

        <B>Please note:</B> the &Grape; package version &GRAPEVERS;
        or higher must be available and compiled for this function to work.

        <Example><![CDATA[
gap> S := InverseSemigroup(
> PartialPerm( [ 1, 2, 3, 4, 5, 6, 7, 10 ], [ 4, 6, 7, 3, 8, 2, 9, 5 ] ),
> PartialPerm( [ 1, 2, 7, 9 ], [ 5, 6, 4, 3 ] ) );
<inverse partial perm semigroup of rank 10 with 2 generators>
gap> T := InverseSemigroup(Idempotents(S), rec(small := true));;
gap> M := MunnSemigroup(T);;
gap> NrIdempotents(M);
60
gap> NrIdempotents(S);
60]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="OPOIPOPI">
  <ManSection><Heading>Monoids of order preserving functions</Heading>
    <Oper Name="OrderEndomorphisms" Arg="n" Label="monoid of order preserving transformations"/>
    <Oper Name="POI" Arg="n" Label="monoid of order preserving partial perms"/>
    <Oper Name="POPI" Arg="n" Label="monoid of orientation preserving partial
      perms"/>
    <Returns>A semigroup of transformations or partial permutations related
      to a linear order. 
    </Returns>
    <Description>
      <List>
        <Mark><C>OrderEndomorphisms(<A>n</A>)</C></Mark>
        <Item>
          <C>OrderEndomorphisms(<A>n</A>)</C> returns the monoid of
          transformations that preserve the usual order on <M>\{1,2,\ldots,
            n\}</M> where <A>n</A> is a positive integer. 
          <Alt Not="Text"> 
            <C>OrderEndomorphisms(<A>n</A>)</C> is generated by the
            <M><A>n+1</A></M> transformations:
            <Display>
              \left(
              \begin{array}{ccccccccc}
              1&amp;2&amp;3&amp;\cdots&amp;n-1&amp; n\\
              1&amp;1&amp;2&amp;\cdots&amp;n-2&amp;n-1
              \end{array}\right), \qquad
              \left(
              \begin{array}{ccccccccc}
              1&amp;2&amp;\cdots&amp;i-1&amp; i&amp; i+1&amp;i+2&amp;\cdots
              &amp;n\\
              1&amp;2&amp;\cdots&amp;i-1&amp; i+1&amp;i+1&amp;i+2&amp;\cdots
              &amp;n\\
              \end{array}\right)
            </Display> 
            where <M>i=0,\ldots,n-1</M> and has <M>{2n-1\choose n-1}</M>
            elements.
          </Alt>
      </Item>
      <Mark><C>POI(<A>n</A>)</C></Mark>
      <Item>
      <C>POI(<A>n</A>)</C> returns the inverse
      monoid of partial permutations that preserve the usual order
      on <M>\{1,2,\ldots, n\}</M> where <A>n</A> is a positive integer.
      <Alt Not="Text">
      <C>POI(<A>n</A>)</C> is generated by the <M><A>n</A></M> 
      partial permutations:
      <Display>
      \left(
      \begin{array}{ccccc}
      1&amp;2&amp;3&amp;\cdots&amp;n\\          
      -&amp;1&amp;2&amp;\cdots&amp;n-1
      \end{array}\right), \qquad
      \left(
      \begin{array}{ccccccccc}
      1&amp;2&amp;\cdots&amp;i-1&amp; i&amp; i+1&amp;i+2&amp;\cdots
      &amp;n\\
      1&amp;2&amp;\cdots&amp;i-1&amp; i+1&amp;-&amp;i+2&amp;\cdots&amp;n\\
      \end{array}\right)
    </Display>
    where <M>i=1, \ldots, n-1</M>
    and has <M>{2n\choose n}</M> elements. </Alt>
  </Item>
  <Mark><C>POPI(<A>n</A>)</C></Mark>
  <Item>
    <C>POPI(<A>n</A>)</C> returns the inverse monoid of partial permutation
    that preserve the orientation of <M>\{1,2,\ldots, n\}</M> where
    <M>n</M> is a positive integer.
    <Alt Not="Text">

    <C>POPI(<A>n</A>)</C> is generated by the partial permutations:
    <Display>
      \left(
      \begin{array}{ccccc}
1&amp;2&amp;\cdots&amp;n-1&amp;n\\
2&amp;3&amp;\cdots&amp;n&amp;1
\end{array}\right),\qquad
\left(
\begin{array}{cccccc}
1&amp;2&amp;\cdots&amp;n-2&amp;n-1&amp;n\\
1&amp;2&amp;\cdots&amp;n-2&amp;n&amp;-
\end{array}\right).
    </Display>
    and has <M>1+\frac{n}{2}{2n\choose n}</M> elements. 
    </Alt>
  </Item>
</List>
      <Example><![CDATA[
gap> S:=POPI(10);                                            
<inverse partial perm monoid of rank 10 with 2 generators>
gap> Size(S);
923781
gap> 1+5*Binomial(20, 10);
923781
gap> S:=POI(10);
<inverse partial perm monoid of rank 10 with 10 generators>
gap> Size(S);
184756
gap> Binomial(20,10);
184756
gap> IsSubsemigroup(POPI(10), POI(10));
true
gap> S:=OrderEndomorphisms(5);
<regular transformation monoid of degree 5 with 5 generators>
gap> IsIdempotentGenerated(S);
true
gap> Size(S)=Binomial(2*5-1, 5-1);
true]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="SingularTransformationSemigroup">
    <ManSection>
      <Oper Name="SingularTransformationSemigroup" Arg="n"/>
      <Oper Name="SingularTransformationMonoid" Arg="n"/>
      <Returns>The semigroup of non-invertible transformations.</Returns>
      <Description>
        If <A>n</A> is a integer greater than 1, then this function
        returns the semigroup of non-invertible transformations, which is
        generated by the <C><A>n</A>(<A>n</A>-1)</C> idempotents of degree
        <A>n</A> and rank <C><A>n</A>-1</C> and has <M>n^n-n!</M> elements. 

        <Example><![CDATA[
gap> S:=SingularTransformationSemigroup(5);
<regular transformation semigroup ideal of degree 5 with 1 generator>
gap> Size(S);
3005]]></Example>
      </Description>
    </ManSection>
<#/GAPDoc>

<#GAPDoc Label="RegularBinaryRelationSemigroup">
<ManSection>
  <Oper Name="RegularBinaryRelationSemigroup" Arg="n"/>
  <Returns>A semigroup of binary relations.</Returns>
  <Description> 
    <C>RegularBinaryRelationSemigroup</C> return the semigroup generated by
    the regular binary relations on the set <M>\{1,\ldots, <A>n</A>\}</M> for a
    positive integer <A>n</A>. 
    <Alt Not="Text"> <C>RegularBinaryRelationSemigroup(<A>n</A>)</C> is
      generated by the <M>4</M> binary relations:
      <Display>
        \begin{array}{ll} 
        \left(\begin{array}{ccccccccc}
        1&amp;2&amp;\cdots&amp;n-1&amp; n\\
        2&amp;3&amp;\cdots&amp;n&amp;1
        \end{array}\right),&amp; \quad
        \left(\begin{array}{ccccccccc}
        1&amp;2&amp;3&amp;\cdots&amp;n\\
          2&amp;1&amp;3&amp;\cdots&amp;n
        \end{array}\right),\\
        \left(\begin{array}{ccccccccc}
        1&amp;2&amp;\cdots&amp;n-1&amp; n\\
        2&amp;2&amp;\cdots&amp;n-1&amp;\{1,n\}
        \end{array}\right), &amp;\quad
        \left(\begin{array}{ccccccccc}
        1&amp;2&amp;\cdots&amp;n-1&amp;n\\
        2&amp;2&amp;\cdots&amp;n-1&amp;-
        \end{array}\right).
        \end{array}
      </Display> 
    </Alt>
    This semigroup has nearly <M>2^{(n^2)}</M> elements. 
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="MonogenicSemigroup">
  <ManSection>
    <Func Name="MonogenicSemigroup" Arg="[filt, ]m, r"/>
    <Returns>
      A monogenic semigroup with index <A>m</A> and period <A>r</A>.
    </Returns>
      <Description>
        If <A>m</A> and <A>r</A> are positive integers,
        then this function returns a monogenic semigroup
        <C>S</C> with index <A>m</A> and period <A>r</A>
        in the category given by the filter <A>filt</A>. <P/>

        The optional argument <A>filt</A> may be one of the following:

        <List>
          <Item><C>IsTransformationSemigroup</C>
            (the default, if <A>filt</A> is not specified),</Item>
          <Item><C>IsPartialPermSemigroup</C>,</Item>
          <Item><C>IsBipartitionSemigroup</C>,</Item>
          <Item><C>IsBlockBijectionSemigroup</C>.</Item>
        </List>

        The semigroup <C>S</C> is generated by a single element, <M>f</M>.
        <C>S</C> consists of the elements
        <M>f, f ^ {2}, \ldots, f ^ {m}, \ldots, f ^ {m + r - 1}</M>.
        The minimal ideal of <C>S</C> consists of the elements
        <M>f ^ {m}, \ldots, f ^ {m + r - 1}</M>
        and is isomorphic to the cyclic group of order <M>r</M>. <P/>

        See <Ref Prop="IsMonogenicSemigroup"/> for more information
        about monogenic semigroups.

        <Example><![CDATA[
gap> S := MonogenicSemigroup(5, 3);
<commutative non-regular transformation semigroup of size 7, degree 8 
 with 1 generator>
gap> IsMonogenicSemigroup(S);
true
gap> I := MinimalIdeal(S);
<commutative simple transformation semigroup ideal of degree 8 with
  1 generator>
gap> IsGroupAsSemigroup(I);
true
gap> StructureDescription(I);
"C3"
gap> S := MonogenicSemigroup(IsBlockBijectionSemigroup, 9, 1);
<commutative non-regular bipartition semigroup of size 9, degree 10 
 with 1 generator>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="RectangularBand">
  <ManSection>
    <Func Name="RectangularBand" Arg="[filt, ]m, n"/>
    <Returns>
      An <A>m</A> by <A>n</A> rectangular band.
    </Returns>
      <Description>
        If <A>m</A> and <A>n</A> are positive integers,
        then this function returns a semigroup isomorphic to an <A>m</A>
        by <A>n</A> rectangular band, which is in the category given by
        the filter <A>filt</A>. <P/>

        The optional argument <A>filt</A> may be one of the following:

        <List>
          <Item><C>IsTransformationSemigroup</C>,</Item>
          <Item><C>IsBipartitionSemigroup</C>,</Item>
          <Item><C>IsReesMatrixSemigroup</C>
            (the default, if <A>filt</A> is not specified).</Item>
        </List>

        See <Ref Prop="IsRectangularBand"/> for more information about
        rectangular bands.

        <Example><![CDATA[
gap> S := RectangularBand(4, 8);
<Rees matrix semigroup 4x8 over Group(())>
gap> IsRectangularBand(S);
true
gap> IsCompletelySimpleSemigroup(S) and IsHTrivial(S);
true
gap> T := RectangularBand(IsTransformationSemigroup, 5, 6);
<transformation semigroup of size 30, degree 31 with 6 generators>
gap> IsRectangularBand(T);
true]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="ZeroSemigroup">
  <ManSection>
    <Func Name="ZeroSemigroup" Arg="[filt, ]n"/>
    <Returns>
      A zero semigroup of order <A>n</A>.
    </Returns>
      <Description>
        If <A>n</A> is a positive integer, then this function returns a zero
        semigroup of order <A>n</A> in the category given by the filter
        <A>filt</A>. <P/>

        The optional argument <A>filt</A> may be one of the following:

        <List>
          <Item><C>IsTransformationSemigroup</C>,</Item>
          <Item><C>IsPartialPermSemigroup</C>
            (the default, if <A>filt</A> is not specified),</Item>
          <Item><C>IsBipartitionSemigroup</C>,</Item>
          <Item><C>IsBlockBijectionSemigroup</C>,</Item>
          <Item><C>IsReesZeroMatrixSemigroup</C>
            (provided that <M><A>n</A> &gt; 1</M>).</Item>
        </List>       

        See <Ref Prop="IsZeroSemigroup"/> for more information about zero
        semigroups.

        <Example><![CDATA[
gap> S := ZeroSemigroup(15);
<non-regular partial perm semigroup of size 15, rank 14 with 14 
 generators>
gap> Size(S);
15
gap> z := MultiplicativeZero(S);
<empty partial perm>
gap> IsZeroSemigroup(S);
true
gap> ForAll(S, x -> ForAll(S, y -> x * y = z));
true
gap> S := ZeroSemigroup(IsReesZeroMatrixSemigroup, 5);
<Rees 0-matrix semigroup 4x1 over Group(())>
gap> Matrix(S);
[ [ 0, 0, 0, 0 ] ]
gap> IsZeroSemigroup(S);
true]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>


<#GAPDoc Label="LeftZeroSemigroup">
  <ManSection>
    <Func Name="LeftZeroSemigroup" Arg="[filt, ]n"/>
    <Func Name="RightZeroSemigroup" Arg="[filt, ]n"/>
    <Returns>
      A left zero (or right zero) semigroup of order <A>n</A>.
    </Returns>
    <Description>
        If <A>n</A> is a positive integer, then this function returns a left
        zero (or right zero, as appropriate) semigroup of order <A>n</A> in the
        category given by the filter <A>filt</A>. <P/>

        The optional argument <A>filt</A> may be one of the following:

        <List>
          <Item><C>IsTransformationSemigroup</C>
            (the default, if <A>filt</A> is not specified),</Item>
          <Item><C>IsBipartitionSemigroup</C>,</Item>
          <Item><C>IsReesMatrixSemigroup</C>.</Item>
        </List>

        See <Ref Prop="IsLeftZeroSemigroup"/> and <Ref
          Prop="IsRightZeroSemigroup"/> for more information about left and
        right zero semigroups.
      
        <Example><![CDATA[
gap> S := LeftZeroSemigroup(20);
<transformation semigroup of size 20, degree 21 with 20 generators>
gap> IsLeftZeroSemigroup(S);
true
gap> ForAll(Tuples(S, 2), p -> p[1] * p[2] = p[1]);
true
gap> S := RightZeroSemigroup(IsBipartitionSemigroup, 5);
<bipartition semigroup of size 5, degree 3 with 5 generators>
gap> IsRightZeroSemigroup(S);
true]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>
