#############################################################################
##
#W  conglatt.xml
#Y  Copyright (C) 2016-2022                                 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"/>
    <Filt Name = "IsCayleyDigraphOfCongruences" 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> only if the congruence numbered
      <C>i</C> is a subrelation of the congruence numbered <C>j</C>.  To avoid
      using an unnecessarily large amount of memory in some cases,
      a congruence poset does not necessarily belong to
      <Ref Prop="IsPartialOrderDigraph" BookName="Digraphs"/>. In other words,
      although every congruence poset represents a partial order it is not
      necessarily the case that there is 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>. <P/>

      The list of congruences can be obtained using <Ref Attr =
        "CongruencesOfPoset"/>; and the underlying semigroup of the poset can
      be obtained using <Ref Attr="UnderlyingSemigroupOfCongruencePoset"/>.<P/>

      Congruence posets can be created using any of:
      <List>
        <Item>
          <Ref Oper = "PosetOfCongruences"/>,
        </Item>
        <Item>
          <Ref Oper = "JoinSemilatticeOfCongruences"/>
        </Item>
        <Item>
          <Ref Attr = "LatticeOfCongruences" Label="for a semigroup"/>,
          <Ref Attr = "LatticeOfLeftCongruences" Label="for a semigroup"/>, or
          <Ref Attr = "LatticeOfRightCongruences" Label="for a semigroup"/>
        </Item>
        <Item>
          <Ref Attr = "CayleyDigraphOfCongruences" Label="for a semigroup"/>,
          <Ref Attr = "CayleyDigraphOfLeftCongruences" Label="for a semigroup"/>, or
          <Ref Attr = "CayleyDigraphOfRightCongruences" Label="for a semigroup"/>.
        </Item>
      </List>

      <C>IsCayleyDigraphOfCongruences</C> only applies to the output of
          <Ref Oper = "JoinSemilatticeOfCongruences"/>,
      <Ref Attr = "CayleyDigraphOfCongruences" Label="for a semigroup"/>,
      <Ref Attr = "CayleyDigraphOfLeftCongruences" Label="for a semigroup"/>, and
      <Ref Attr = "CayleyDigraphOfRightCongruences" Label="for a semigroup"/>.
      The congruences used as the generating set for these operations can be obtained using
      <Ref Attr="GeneratingCongruencesOfJoinSemilattice"/>.

      <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> IsIsomorphicDigraph(poset,
> Digraph([[1, 2, 3, 4], [2], [2, 3], [2, 3, 4]]));
true
gap> T := FullTransformationMonoid(3);;
gap> congs := PrincipalCongruencesOfSemigroup(T);;
gap> poset := JoinSemilatticeOfCongruences(PosetOfCongruences(congs));
<lattice of 6 two-sided congruences over
 <full transformation monoid of degree 3>>
gap> IsCayleyDigraphOfCongruences(poset);
false
gap> IsCongruencePoset(poset);
true
gap> DigraphNrVertices(poset);
6
gap> poset := CayleyDigraphOfCongruences(T);
<poset of 7 two-sided congruences over
 <full transformation monoid of degree 3>>
gap> IsCayleyDigraphOfCongruences(poset);
true
]]></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 list or collection"/>
    <Oper Name = "LatticeOfLeftCongruences" Arg = "S, restriction"
          Label = "for a semigroup and a list or collection"/>
    <Oper Name = "LatticeOfRightCongruences" Arg = "S, restriction"
          Label = "for a semigroup and a list or collection"/>
    <Returns>A lattice digraph.</Returns>
    <Description>
      If <A>S</A> is a semigroup, then <C>LatticeOfCongruences</C> returns 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> IsIsomorphicDigraph(LatticeOfRightCongruences(S),
> Digraph([[1, 2, 3, 4, 5], [2], [2, 3], [2, 4], [2, 5]]));
true
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="CayleyDigraphOfCongruences">
  <ManSection>
    <Attr Name = "CayleyDigraphOfCongruences"
          Arg = "S"
          Label = "for a semigroup"/>
    <Attr Name = "CayleyDigraphOfLeftCongruences"
          Arg = "S"
          Label = "for a semigroup"/>
    <Attr Name = "CayleyDigraphOfRightCongruences"
          Arg = "S"
          Label = "for a semigroup"/>
    <Oper Name = "CayleyDigraphOfCongruences"
          Arg = "S, restriction"
          Label = "for a semigroup and a list or collection"/>
    <Oper Name = "CayleyDigraphOfLeftCongruences"
          Arg = "S, restriction"
          Label = "for a semigroup and a list or collection"/>
    <Oper Name = "CayleyDigraphOfRightCongruences"
          Arg = "S, restriction"
          Label = "for a semigroup and a list or collection"/>
    <Returns>A digraph.</Returns>
    <Description>
      If <A>S</A> is a semigroup, then <C>CayleyDigraphOfCongruences</C>
      returns the right Cayley graph of the semilattice of congruences of
      <A>S</A> with respect to the generating set consisting of the principal
      congruences congruence poset.
      See <Ref Filt = "IsCayleyDigraphOfCongruences"/> for more details. <P/>

      <C>CayleyDigraphOfLeftCongruences</C> and
      <C>CayleyDigraphOfRightCongruences</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/>

      Note that <Ref Attr="LatticeOfCongruences" Label="for a semigroup"/>, and
      its analogues for right and left congruences, return the reflexive
      transitive closure of the digraph returned by this function (with any
      multiple edges removed). If there are a large number of congruences, then
      it might be the case that forming the reflexive transitive closure takes
      a significant amount of time, and so it might be desirable to use this
      function instead. <P/>

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

      <Example><![CDATA[
gap> S := OrderEndomorphisms(2);;
gap> CayleyDigraphOfCongruences(S);
<poset of 3 two-sided congruences over <regular transformation monoid
 of size 3, degree 2 with 2 generators>>
gap> CayleyDigraphOfLeftCongruences(S);
<poset of 3 left congruences over <regular transformation monoid
 of size 3, degree 2 with 2 generators>>
gap> CayleyDigraphOfRightCongruences(S);
<poset of 5 right congruences over <regular transformation monoid
 of size 3, degree 2 with 2 generators>>
gap> IsIsomorphicDigraph(CayleyDigraphOfRightCongruences(S),
> Digraph([[2, 3, 4], [2, 5, 5], [5, 3, 5], [5, 5, 4], [5, 5, 5]]));
true
gap> S := FullTransformationMonoid(4);;
gap> restriction := [Transformation([1, 1, 1, 1]),
>                    Transformation([1, 1, 1, 2]),
>                    Transformation([1, 1, 1, 3])];;
gap> CayleyDigraphOfCongruences(S, Combinations(restriction, 2));
<poset 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);
[ <2-sided 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.
      See also <Ref Oper = "JoinSemilatticeOfCongruences"/>,
      <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>
    <Attr Name = "JoinSemilatticeOfCongruences" Arg = "poset"/>
    <Returns>A congruence poset.</Returns>
    <Description>
      If <A>poset</A> is a congruence poset (i.e. it satisfies
      <Ref Filt = "IsCongruencePoset"/>), then
     this function returns the congruence poset formed by these congruences
      partially ordered by containment, along with all their joins.
      This includes the empty join which equals the trivial congruence.
      <P/>

      The digraph returned by this function represents the Cayley graph of
      the semilattice generated by <Ref Attr="CongruencesOfPoset"/> with
      identity adjoined. The reflexive transitive closure of this digraph is a
      join semillatice in the sense of
      <Ref Prop="IsJoinSemilatticeDigraph" BookName="Digraphs"/>.
      <P/>

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

      <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> D := JoinSemilatticeOfCongruences(PosetOfCongruences(coll));
<poset of 4 right congruences over
 <symmetric inverse monoid of degree 2>>
gap> IsJoinSemilatticeDigraph(DigraphReflexiveTransitiveClosure(D));
true]]></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>

<#GAPDoc Label="GeneratingCongruencesOfJoinSemilattice">
  <ManSection>
    <Attr Name = "GeneratingCongruencesOfJoinSemilattice" Arg="poset"/>
    <Returns>A list of congruences.</Returns>
    <Description>
      If <A>poset</A> satisfies <Ref Filt="IsCayleyDigraphOfCongruences"/>,
      then this attribute holds the generating set for the semilattice of
      congruences (where the operation is join).

      <Example><![CDATA[
gap> S := OrderEndomorphisms(3);;
gap> D := CayleyDigraphOfCongruences(S);
<poset of 4 two-sided congruences over <regular transformation monoid
 of size 10, degree 3 with 3 generators>>
gap> GeneratingCongruencesOfJoinSemilattice(D);
[ <universal semigroup congruence over <regular transformation monoid
     of size 10, degree 3 with 3 generators>>,
  <2-sided semigroup congruence over <regular transformation monoid
     of size 10, degree 3 with 3 generators> with 1 generating pairs>,
  <2-sided semigroup congruence over <regular transformation monoid
     of size 10, degree 3 with 3 generators> with 1 generating pairs>
 ]
]]></Example>
    </Description>
  </ManSection>
  <#/GAPDoc>
