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

<#GAPDoc Label="IsPBRSemigroup">
  <ManSection>
    <Filt Name = "IsPBRSemigroup" Arg = "S"/>
    <Filt Name = "IsPBRMonoid" Arg = "S"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
      A <E>PBR semigroup</E> is simply a semigroup consisting of
      PBRs. An object <A>obj</A> is a PBR semigroup in &GAP; if
      it satisfies <Ref Prop = "IsSemigroup" BookName = "ref"/> and
      <Ref Filt = "IsPBRCollection"/>.<P/>

      A <E>PBR monoid</E> is a monoid consisting of PBRs. 
      An object <A>obj</A> is a PBR monoid in &GAP; if it satisfies 
      <Ref Prop = "IsMonoid" BookName = "ref"/> and
      <Ref Filt = "IsPBRCollection"/>.<P/>

      Note that it is possible for a PBR semigroup to have a multiplicative
      neutral element (i.e. an identity element) but not to satisfy
      <C>IsPBRMonoid</C>. For example,

      <Example><![CDATA[
gap> x := PBR([[-2, -1, 3], [-2, 2], [-3, -2, 1, 2, 3]],
>             [[-3, -2, -1, 2, 3], [-3, -2, -1, 2, 3], [-1]]);;
gap> S := Semigroup(x, One(x));
<commutative pbr monoid of degree 3 with 1 generator>
gap> IsMonoid(S);
true
gap> IsPBRMonoid(S);
true
gap> S := Semigroup([
>  PBR([[-2, 1], [-3, 2], [-1, 3], [-4, 4, 5], [-4, 4, 5]],
>      [[-1, 3], [-2, 1], [-3, 2], [-4, 4, 5], [-5]]),
>  PBR([[-2, 1], [-1, 2], [-3, 3], [-4, 4, 5], [-4, 4, 5]],
>      [[-1, 2], [-2, 1], [-3, 3], [-4, 4, 5], [-5]]),
>  PBR([[-1, 1, 3], [-2, 2], [-1, 1, 3], [-4, 4, 5], [-4, 4, 5]],
>      [[-1, 1, 3], [-2, 2], [-3], [-4, 4, 5], [-5]])]);
<pbr semigroup of degree 5 with 3 generators>
gap> One(S);
fail
gap> MultiplicativeNeutralElement(S);
PBR([ [ -1, 1 ], [ -2, 2 ], [ -3, 3 ], [ -4, 4, 5 ], [ -4, 4, 5 ] ], 
  [ [ -1, 1 ], [ -2, 2 ], [ -3, 3 ], [ -4, 4, 5 ], [ -5 ] ])
gap> IsPBRMonoid(S);
false]]></Example>
      In this example <C>S</C> cannot be converted into a monoid using <Ref
        Oper = "AsMonoid" BookName = "ref"/> since the <Ref Attr = "One"
        BookName = "ref"/> of any element in <C>S</C> differs from the
      multiplicative neutral element. <P/>

      For more details see <Ref Filt = "IsMagmaWithOne" BookName = "ref"/>.
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="DegreeOfPBRSemigroup">
  <ManSection>
    <Attr Name = "DegreeOfPBRSemigroup" Arg = "S"/>
    <Returns>A non-negative integer.</Returns>
    <Description>
      The <E>degree</E> of a PBR semigroup <A>S</A> is just the
      degree of any (and every) element of <A>S</A>.

      <Example><![CDATA[
gap> S := Semigroup(
>  PBR([[-1, 1], [-2, 2], [-3, 3]],
>      [[-1, 1], [-2, 2], [-3, 3]]),
>  PBR([[1, 2], [1, 2], [-3, 3]],
>      [[-2, -1], [-2, -1], [-3, 3]]),
>  PBR([[-1, 1], [2, 3], [2, 3]],
>      [[-1, 1], [-3, -2], [-3, -2]]));
<pbr semigroup of degree 3 with 3 generators>
gap> DegreeOfPBRSemigroup(S);
3]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsomorphismPBRSemigroup">
  <ManSection>
    <Attr Name = "IsomorphismPBRSemigroup" Arg = "S"/>
    <Returns>An isomorphism.</Returns>
    <Description>
      If <A>S</A> is a semigroup, then <C>IsomorphismPBRSemigroup</C> returns
      an isomorphism from <A>S</A> to a PBR semigroup. When <A>S</A> is a
      transformation or bipartition semigroup of degree <C>n</C>,
      <C>IsomorphismPBRSemigroup</C> returns the
      natural embedding of <A>S</A> into the full pbr monoid on <C>n</C>
      points. <P/>
 
      When <A>S</A> is any other type of semigroup, this function returns the
      composition of an isomorphism from <A>S</A> to a transformation
      semigroup, and an isomorphism from that transformation semigroup into a
      PBR semigroup.
      <P/>

      See <Ref Oper = "AsPBRSemigroup"/>.
      <Example><![CDATA[
gap> S := InverseSemigroup([
> PartialPerm([2, 6, 7, 0, 0, 9, 0, 1, 0, 5]),
> PartialPerm([3, 8, 1, 9, 0, 4, 10, 5, 0, 6])]);;
gap> AsSemigroup(IsPBRSemigroup, S);
<pbr semigroup of degree 11 with 4 generators>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="FullPBRMonoid">
  <ManSection>
    <Oper Name = "FullPBRMonoid" Arg = "n"/>
    <Returns>A PBR monoid.</Returns>
    <Description>
      If <A>n</A> is a positive integer not greater than <C>2</C>, then this
      operation returns the monoid consisting of all of the partitioned binary
      relations (PBRs) of degree <A>n</A>; called the <E>full PBR monoid</E>.
      There are <C>2 ^ ((2 * n) ^ 2)</C> PBRs of degree <A>n</A>.  The full PBR
      monoid of degree <A>n</A> is currently too large to compute when
      <M><A>n</A> \geq 3</M>. <P/>

      The full PBR monoid is not regular in general.

      <Example><![CDATA[
gap> S := FullPBRMonoid(1);
<pbr monoid of degree 1 with 4 generators>
gap> S := FullPBRMonoid(2);
<pbr monoid of degree 2 with 10 generators>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>
