#############################################################################
##
#W  conglatt.xml
#Y  Copyright (C) 2016                                      Michael Young
##
##  Licensing information can be found in the README file of this package.
##
#############################################################################
##

<#GAPDoc Label="IsCongruencePoset">
  <ManSection>
    <Filt Name = "IsCongruencePoset" Arg = "poset" Type = "Category"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
      This category contains all congruence posets.  A <E>congruence poset</E>
      is a partially ordered set of congruences over a specific semigroup, where
      the ordering is defined by containment according
      to <Ref Oper = "IsSubrelation"/>: given two congruences <C>cong1</C> and
      <C>cong2</C>, we say that <C>cong1</C> &lt; <C>cong2</C> if and only if
      <C>cong1</C> is a subrelation (a refinement) of <C>cong2</C>. The
      congruences in a congruence poset can be left, right, or two-sided. <P/>

      A congruence poset is a digraph
      (see <Ref Filt = "IsDigraph" BookName = "Digraphs"/>) with a vertex for
      each congruence, and an edge from vertex <C>i</C> to vertex <C>j</C> if
      and only if the congruence numbered <C>i</C> is a subrelation of the
      congruence numbered <C>j</C>.  The list of congruences can be obtained
      using <Ref Attr = "CongruencesOfPoset"/>. <P/>

      Congruence posets can be created using <Ref Oper = "PosetOfCongruences"/>,
      <Ref Oper = "JoinSemilatticeOfCongruences"
           Label = "for a list or collection and a function"/>, and
      <Ref Attr = "LatticeOfCongruences" Label = "for a semigroup"/>. <P/>

      <Example><![CDATA[
gap> S := SymmetricInverseMonoid(2);;
gap> poset := LatticeOfCongruences(S);
<lattice of 4 two-sided congruences over 
 <symmetric inverse monoid of degree 2>>
gap> IsCongruencePoset(poset);
true
gap> IsDigraph(poset);
true
gap> OutNeighbours(poset);
[ [ 1, 2, 3, 4 ], [ 2 ], [ 2, 3 ], [ 2, 3, 4 ] ]
gap> T := FullTransformationMonoid(3);;
gap> congs := PrincipalCongruencesOfSemigroup(T);;
gap> poset := JoinSemilatticeOfCongruences(PosetOfCongruences(congs),
>                                          WrappedTwoSidedCongruence);
<lattice of 6 two-sided congruences over 
 <full transformation monoid of degree 3>>
gap> IsCongruencePoset(poset);
true
gap> DigraphNrVertices(poset);
6
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="LatticeOfCongruences">
  <ManSection>
    <Attr Name = "LatticeOfCongruences" Arg = "S"
          Label = "for a semigroup"/>
    <Attr Name = "LatticeOfLeftCongruences" Arg = "S"
          Label = "for a semigroup"/>
    <Attr Name = "LatticeOfRightCongruences" Arg = "S"
          Label = "for a semigroup"/>
    <Oper Name = "LatticeOfCongruences" Arg = "S, restriction"
          Label = "for a semigroup and a multiplicative element collection"/>
    <Oper Name = "LatticeOfLeftCongruences" Arg = "S, restriction"
          Label = "for a semigroup and a multiplicative element collection"/>
    <Oper Name = "LatticeOfRightCongruences" Arg = "S, restriction"
          Label = "for a semigroup and a multiplicative element collection"/>
    <Returns>A list of lists.</Returns>
    <Description>
      If <A>S</A> is a semigroup, then <C>LatticeOfCongruences</C> gives a
      congruence poset object containing all the congruences of <A>S</A> and
      information about how they are contained in each other.
      See <Ref Filt = "IsCongruencePoset"/> for more details. <P/>

      <C>LatticeOfLeftCongruences</C> and <C>LatticeOfRightCongruences</C> do
      the same thing for left and right congruences respectively. <P/>

      If <A>restriction</A> is specified and is a collection of elements from
      <A>S</A>, then the result will only include congruences generated by pairs
      of elements from <A>restriction</A>.  Otherwise, all congruences will be
      calculated.<P/>

      See <Ref Attr = "CongruencesOfSemigroup" Label = "for a semigroup"/>. <P/>

      <Example><![CDATA[
gap> S := OrderEndomorphisms(2);;
gap> LatticeOfCongruences(S);
<lattice of 3 two-sided congruences over <regular transformation 
 monoid of size 3, degree 2 with 2 generators>>
gap> LatticeOfLeftCongruences(S);
<lattice of 3 left congruences over <regular transformation monoid 
 of size 3, degree 2 with 2 generators>>
gap> LatticeOfRightCongruences(S);
<lattice of 5 right congruences over <regular transformation monoid 
 of size 3, degree 2 with 2 generators>>
gap> OutNeighbours(LatticeOfRightCongruences(S));
[ [ 1, 2, 3, 4, 5 ], [ 2 ], [ 2, 3 ], [ 2, 4 ], [ 2, 5 ] ]
gap> S := FullTransformationMonoid(4);;
gap> restriction := [Transformation([1, 1, 1, 1]),
>                    Transformation([1, 1, 1, 2]),
>                    Transformation([1, 1, 1, 3])];;
gap> latt := LatticeOfCongruences(S, Combinations(restriction, 2));
<lattice of 2 two-sided congruences over 
 <full transformation monoid of degree 4>>
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="PosetOfPrincipalCongruences">
  <ManSection>
    <Attr Name = "PosetOfPrincipalCongruences" Arg = "S"
          Label = "for a semigroup"/>
    <Attr Name = "PosetOfPrincipalLeftCongruences" Arg = "S"
          Label = "for a semigroup"/>
    <Attr Name = "PosetOfPrincipalRightCongruences" Arg = "S"
          Label = "for a semigroup"/>
    <Oper Name = "PosetOfPrincipalCongruences" Arg = "S, restriction"
          Label = "for a semigroup and a multiplicative element collection"/>
    <Oper Name = "PosetOfPrincipalLeftCongruences" Arg = "S, restriction"
          Label = "for a semigroup and a multiplicative element collection"/>
    <Oper Name = "PosetOfPrincipalRightCongruences" Arg = "S, restriction"
          Label = "for a semigroup and a multiplicative element collection"/>
    <Returns>A congruence poset.</Returns>
    <Description>
      If <A>S</A> is a semigroup, then <C>PosetOfPrincipalCongruences</C>
      returns a congruence poset object which contains all the principal
      congruences of <A>S</A>, ordered by containment according to
      <Ref Oper = "IsSubrelation"/>.  A congruence is <E>principal</E> if it can
      be defined by a single generating pair.

      <C>PosetOfPrincipalLeftCongruences</C> and
      <C>PosetOfPrincipalRightCongruences</C> do the same thing for left and
      right congruences respectively. <P/>

      If <A>restriction</A> is specified and is a collection of elements from
      <A>S</A>, then the result will only include principal congruences
      generated by pairs of elements from <A>restriction</A>.  Otherwise, all
      principal congruences will be calculated.<P/>

      See also <Ref Attr = "LatticeOfCongruences" Label = "for a semigroup"/>
      and <Ref Attr = "PrincipalCongruencesOfSemigroup"
               Label = "for a semigroup"/>. <P/>

      <Example><![CDATA[
gap> S := Semigroup(Transformation([1, 3, 1]),
>                   Transformation([2, 3, 3]));;
gap> PosetOfPrincipalLeftCongruences(S);
<poset of 12 left congruences over <transformation semigroup 
 of size 11, degree 3 with 2 generators>>
gap> PosetOfPrincipalCongruences(S);
<lattice of 3 two-sided congruences over <transformation semigroup 
 of size 11, degree 3 with 2 generators>>
gap> restriction := [Transformation([3, 2, 3]),
>                    Transformation([3, 1, 3]),
>                    Transformation([2, 2, 2])];;
gap> poset := PosetOfPrincipalRightCongruences(S, 
> Combinations(restriction, 2));
<poset of 3 right congruences over <transformation semigroup 
 of size 11, degree 3 with 2 generators>>
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="CongruencesOfPoset">
  <ManSection>
    <Attr Name = "CongruencesOfPoset" Arg = "poset"/>
    <Returns>A list.</Returns>
    <Description>
      If <A>poset</A> is a congruence poset object, then this attribute returns
      a list of all the congruence objects in the poset (these may be left,
      right, or two-sided).  The order of this list corresponds to the order of
      the entries in the poset. <P/>

      See also <Ref Attr = "LatticeOfCongruences" Label = "for a semigroup"/>
      and <Ref Attr = "CongruencesOfSemigroup" Label = "for a semigroup"/>. <P/>

      <Example><![CDATA[
gap> S := OrderEndomorphisms(2);;
gap> latt := LatticeOfRightCongruences(S);
<lattice of 5 right congruences over <regular transformation monoid 
 of size 3, degree 2 with 2 generators>>
gap> CongruencesOfPoset(latt);
[ <right semigroup congruence over <regular transformation monoid 
     of size 3, degree 2 with 2 generators> with 0 generating pairs>, 
  <right semigroup congruence over <regular transformation monoid 
     of size 3, degree 2 with 2 generators> with 1 generating pairs>, 
  <right semigroup congruence over <regular transformation monoid 
     of size 3, degree 2 with 2 generators> with 1 generating pairs>, 
  <right semigroup congruence over <regular transformation monoid 
     of size 3, degree 2 with 2 generators> with 1 generating pairs>, 
  <right semigroup congruence over <regular transformation monoid 
     of size 3, degree 2 with 2 generators> with 2 generating pairs> ]
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="UnderlyingSemigroupOfCongruencePoset">
  <ManSection>
    <Attr Name = "UnderlyingSemigroupOfCongruencePoset" Arg = "poset"/>
    <Returns>A semigroup.</Returns>
    <Description>
      If <A>poset</A> is a congruence poset object, then this attribute returns
      the semigroup on which all its congruences are defined.

      <Example><![CDATA[
gap> S := OrderEndomorphisms(2);
<regular transformation monoid of degree 2 with 2 generators>
gap> latt := LatticeOfRightCongruences(S);
<lattice of 5 right congruences over <regular transformation monoid 
 of size 3, degree 2 with 2 generators>>
gap> UnderlyingSemigroupOfCongruencePoset(latt) = S;
true
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="PosetOfCongruences">
  <ManSection>
    <Oper Name = "PosetOfCongruences" Arg = "coll"/>
    <Returns>A congruence poset.</Returns>
    <Description>
      If <A>coll</A> is a list or collection of semigroup congruences (which may
      be left, right, or two-sided) then this operation returns the congruence
      poset formed by these congruences partially ordered by containment. <P/>

      This operation does not create any new congruences or take any joins.
      However, see
      <Ref Oper = "JoinSemilatticeOfCongruences"
           Label = "for a list or collection and a function"/>.
      See also <Ref Filt = "IsCongruencePoset"/>
      and <Ref Attr = "LatticeOfCongruences" Label = "for a semigroup"/>. <P/>

      <Example><![CDATA[
gap> S := OrderEndomorphisms(2);;
gap> pair1 := [Transformation([1, 1]), IdentityTransformation];;
gap> pair2 := [IdentityTransformation, Transformation([2, 2])];;
gap> coll := [RightSemigroupCongruence(S, pair1),
>             RightSemigroupCongruence(S, pair2),
>             RightSemigroupCongruence(S, [])];;
gap> poset := PosetOfCongruences(coll);
<poset of 3 right congruences over <regular transformation monoid 
 of size 3, degree 2 with 2 generators>>
gap> OutNeighbours(poset);
[ [ 1 ], [ 2 ], [ 1, 2, 3 ] ]
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="JoinSemilatticeOfCongruences">
  <ManSection>
    <Oper Name = "JoinSemilatticeOfCongruences" Arg = "coll, join_func"
          Label = "for a list or collection and a function"/>
    <Oper Name = "JoinSemilatticeOfCongruences" Arg = "poset, join_func"
          Label = "for a congruence poset and a function"/>
    <Returns>A congruence poset.</Returns>
    <Description>
      If <A>coll</A> is a list or collection of semigroup congruences (which may
      be left, right, or two-sided) and <A>join_func</A> is a function for
      taking the join of two of the congruences (such as
      <Ref Oper = "JoinSemigroupCongruences"/>) then this operation returns the
      congruence poset formed by these congruences partially ordered by
      containment, along with all their joins. <P/>

      Alternatively, a congruence poset <A>poset</A> can be specified; in this
      case, the congruences contained in <A>poset</A> will be used in place of
      <A>coll</A>, and information already known about their containments will
      be used. <P/>

      See also <Ref Filt = "IsCongruencePoset"/>
      and <Ref Oper = "PosetOfCongruences"/>. <P/>

      <Example><![CDATA[
gap> S := SymmetricInverseMonoid(2);;
gap> pair1 := [PartialPerm([1], [1]), PartialPerm([2], [1])];;
gap> pair2 := [PartialPerm([1], [1]), PartialPerm([1, 2], [1, 2])];;
gap> pair3 := [PartialPerm([1, 2], [1, 2]),
>              PartialPerm([1, 2], [2, 1])];;
gap> coll := [RightSemigroupCongruence(S, pair1),
>             RightSemigroupCongruence(S, pair2),
>             RightSemigroupCongruence(S, pair3)];;
gap> JoinSemilatticeOfCongruences(PosetOfCongruences(coll),
> WrappedRightCongruence);
<poset of 4 right congruences over 
 <symmetric inverse monoid of degree 2>>
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="MinimalCongruences">
  <ManSection>
    <Attr Name = "MinimalCongruences" Arg = "coll"
          Label = "for a list or collection"/>
    <Attr Name = "MinimalCongruences" Arg = "poset"
          Label = "for a congruence poset"/>
    <Returns>A list.</Returns>
    <Description>
      If <A>coll</A> is a list or collection of semigroup congruences (which may
      be left, right, or two-sided) then this attribute returns a list of all
      the congruences from <A>coll</A> which do not contain any of the others as
      subrelations. <P/>

      Alternatively, a congruence poset <A>poset</A> can be specified; in this
      case, the congruences contained in <A>poset</A> will be used in place of
      <A>coll</A>, and information already known about their containments will
      be used. <P/>

      This function should not be confused with
      <Ref Attr = "MinimalCongruencesOfSemigroup" Label = "for a semigroup"/>.
      See also <Ref Filt = "IsCongruencePoset"/>
      and <Ref Oper = "PosetOfCongruences"/>. <P/>

      <Example><![CDATA[
gap> S := SymmetricInverseMonoid(2);;
gap> pair1 := [PartialPerm([1], [1]), PartialPerm([2], [1])];;
gap> pair2 := [PartialPerm([1], [1]), PartialPerm([1, 2], [1, 2])];;
gap> pair3 := [PartialPerm([1, 2], [1, 2]),
>              PartialPerm([1, 2], [2, 1])];;
gap> coll := [RightSemigroupCongruence(S, pair1),
>             RightSemigroupCongruence(S, pair2),
>             RightSemigroupCongruence(S, pair3)];;
gap> MinimalCongruences(PosetOfCongruences(coll));
[ <right semigroup congruence over <symmetric inverse monoid of degree\
 2> with 1 generating pairs>, 
  <right semigroup congruence over <symmetric inverse monoid of degree\
 2> with 1 generating pairs> ]
gap> poset := LatticeOfCongruences(S);
<lattice of 4 two-sided congruences over 
 <symmetric inverse monoid of degree 2>>
gap> MinimalCongruences(poset);
[ <2-sided semigroup congruence over <symmetric inverse monoid of degr\
ee 2> with 0 generating pairs> ]
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>
