#############################################################################
##
#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 on 9 pts 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 on 4 pts with 3 generators>
gap> SingularJonesMonoid(8);
<regular bipartition semigroup ideal on 8 pts 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 on 4 pts with 3 generators>
gap> IsSubsemigroup(S, JonesMonoid(4));
true
gap> Size(S);
105
gap> SingularBrauerMonoid(8);
<regular bipartition semigroup ideal on 8 pts with 1 generator>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="FactorisableDualSymmetricInverseSemigroup">
   <ManSection>
    <Oper Name="FactorisableDualSymmetricInverseSemigroup" Arg="n"/>
    <Oper Name="SingularFactorisableDualSymmetricInverseSemigroup" Arg="n"/>
    <Returns>An inverse bipartition monoid.</Returns>
    <Description>
      If <A>n</A> is a positive integer, then this operation returns the largest
      factorisable inverse subsemigroup of the dual symmetric inverse monoid of
      degree <A>n</A>. <P/>
      
      <C>SingularFactorisableDualSymmetricInverseSemigroup</C> returns the ideal
      of the factorisable dual symmetric inverse semigroup 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="IsUniformBlockBijection"/>.
      <Example><![CDATA[
gap> S:=DualSymmetricInverseMonoid(4);
<inverse bipartition monoid on 4 pts with 3 generators>
gap> IsFactorisableSemigroup(S);
false
gap> S:=FactorisableDualSymmetricInverseSemigroup(4);
<inverse bipartition monoid on 4 pts with 3 generators>
gap> IsFactorisableSemigroup(S);
true
gap> S:=Range(IsomorphismBipartitionSemigroup(SymmetricInverseMonoid(5)));
<inverse bipartition monoid on 5 pts 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 on 3 pts with 3 generators>
gap> Size(S);
25
]]></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 on 5 pts with 4 generators>
gap> Size(S);
115975
]]></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 on 9 pts with 4 generators>
gap> Size(last);
43046721]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="FullMatrixSemigroup">
   <ManSection>
    <Oper Name="FullMatrixSemigroup" Arg="d, q"/>
    <Oper Name="GeneralLinearSemigroup" Arg="d, q"/>
    <Returns>A matrix semigroup.</Returns>
    <Description>
      <C>FullMatrixSemigroup</C> and <C>GeneralLinearSemigroup</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>q^(d^2)</C> elements. <P/>

      <B>Please note:</B> there are currently no special methods for computing
      with matrix semigroups in &Semigroups; and so it might be advisable to use
      <Ref Oper="IsomorphismTransformationSemigroup" BookName="ref"/>.

      <Example><![CDATA[
gap> S:=FullMatrixSemigroup(3,4);
<full matrix semigroup 3x3 over GF(2^2)>
gap> T:=Range(IsomorphismTransformationSemigroup(S));;
gap> Size(T);
262144]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsFullMatrixSemigroup">
  <ManSection>
    <Prop Name="IsFullMatrixSemigroup" Arg="S"/>      
    <Prop Name="IsGeneralLinearSemigroup" Arg="S"/>      
    <Description>
      <C>IsFullMatrixSemigroup</C> and <C>IsGeneralLinearSemigroup</C> return
      <K>true</K> if the semigroup <C>S</C> was created using either of the
      commands <Ref Oper="FullMatrixSemigroup"/> or 
      <Ref Oper="GeneralLinearSemigroup"/> and <K>false</K> otherwise. 

      <Example><![CDATA[
gap> S:=RandomTransformationSemigroup(4,4);;
gap> IsFullMatrixSemigroup(S);
false
gap> S:=GeneralLinearSemigroup(3,3);
<full matrix semigroup 3x3 over GF(3)>
gap> IsFullMatrixSemigroup(S);
true]]></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 on 10 pts 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 on 10 pts with 2 generators>
gap> Size(S);
923781
gap> 1+5*Binomial(20, 10);
923781
gap> S:=POI(10);
<inverse partial perm monoid on 10 pts 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 on 5 pts 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 on 5 pts 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>
    <Oper Name="MonogenicSemigroup" Arg="m, r"/>
    <Returns>
      A monogenic transformation 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 transformation semigroup
        <C>S</C> with index <A>m</A> and period <A>r</A>. <P/>

        The semigroup <C>S</C> is generated by a transformation <C>f</C>
        which has index <A>m</A> and period <A>r</A>
        (see <Ref Attr="IndexPeriodOfTransformation" BookName="ref"/>).
        <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.

        <Example><![CDATA[
gap> S := MonogenicSemigroup(5, 3);
<commutative non-regular transformation semigroup of size 7, 
 on 8 pts with 1 generator>
gap> IsMonogenicSemigroup(S);
true
gap> I := MinimalIdeal(S);
<transformation group on 8 pts with 1 generator>
gap> StructureDescription(I);
"C3"]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="ZeroSemigroup">
  <ManSection>
    <Oper Name="ZeroSemigroup" Arg="n"/>
    <Returns>
      A zero partial permutation semigroup of order <A>n</A>.
    </Returns>
      <Description>
        If <A>n</A> is a positive integer,
        then this function returns a zero semigroup consisting of <A>n</A>
        partial permutations. The zero of this semigroup is the
        empty partial permutation. <P/>

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

        <Example><![CDATA[
gap> S := ZeroSemigroup(15);
<partial perm semigroup of size 15, on 14 pts 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]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="RectangularBand">
  <ManSection>
    <Oper Name="RectangularBand" Arg="m, n"/>
    <Returns>
      A Rees matrix semigroup
      isomorphic to 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 Rees matrix semigroup with <A>m</A>
        rows and <A>n</A> columns over the trivial group.
        Such a Rees matrix semigroup is isomorphic to an <A>m</A> by <A>n</A>
        rectangular band. <P/>

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

        <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 := AsTransformationSemigroup(S);
<transformation semigroup on 33 pts with 8 generators>
gap> IsRectangularBand(T);
true]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>
