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

<#GAPDoc Label="TraceOfSemigroupCongruence">
  <ManSection>
    <Attr Name="TraceOfSemigroupCongruence" Arg="cong"/>
    <Returns>A list of lists.</Returns>
    <Description>
      If <A>cong</A> is an inverse semigroup congruence by kernel and trace,
      then this attribute returns the restriction of <A>cong</A> to the
      idempotents of the semigroup.  This is in block form: each idempotent will
      appear in precisely one list, and two idempotents will be in the same list
      if and only if they are related by <A>cong</A>.

      <Example><![CDATA[
gap> I := InverseSemigroup([
>  PartialPerm([2, 3]), PartialPerm([2, 0, 3])]);;
gap> cong := SemigroupCongruence(I,
> [[PartialPerm([0, 1, 3]), PartialPerm([0, 1])],
>  [PartialPerm([]), PartialPerm([1, 2])]]);
<2-sided semigroup congruence over <inverse partial perm semigroup 
 of size 19, rank 3 with 2 generators> with 2 generating pairs>
gap> TraceOfSemigroupCongruence(cong);
[ [ <empty partial perm>, <identity partial perm on [ 1 ]>, 
      <identity partial perm on [ 2 ]>, 
      <identity partial perm on [ 1, 2 ]>, 
      <identity partial perm on [ 3 ]>, 
      <identity partial perm on [ 2, 3 ]>, 
      <identity partial perm on [ 1, 3 ]> ] ]]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="KernelOfSemigroupCongruence">
  <ManSection>
    <Attr Name = "KernelOfSemigroupCongruence" Arg = "cong"/>
    <Returns>
      An inverse semigroup.
    </Returns>
    <Description>
      If <A>cong</A> is a congruence over a semigroup with inverse op,
      then this attribute returns the <E>kernel</E> of that congruence; that
      is, the inverse subsemigroup consisting of all elements which are related
      to an idempotent by <A>cong</A>. <P/>
      <Example><![CDATA[
gap> I := InverseSemigroup([
>  PartialPerm([2, 3]), PartialPerm([2, 0, 3])]);;
gap> cong := SemigroupCongruence(I,
> [[PartialPerm([0, 1, 3]), PartialPerm([0, 1])],
>  [PartialPerm([]), PartialPerm([1, 2])]]);
<2-sided semigroup congruence over <inverse partial perm semigroup 
 of size 19, rank 3 with 2 generators> with 2 generating pairs>
gap> KernelOfSemigroupCongruence(cong);
<inverse partial perm semigroup of size 19, rank 3 with 5 generators>
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="AsInverseSemigroupCongruenceByKernelTrace">
  <ManSection>
    <Attr Name = "AsInverseSemigroupCongruenceByKernelTrace" Arg = "cong"/>
    <Returns>
      An inverse semigroup congruence by kernel and trace.
    </Returns>
    <Description>
      If <A>cong</A> is a semigroup congruence over an inverse semigroup, then
      this attribute returns an object which describes the same congruence, but
      with an internal representation defined by that congruence's kernel and
      trace. <P/>

      See <Cite Key = "Howie1995aa"/> section 5.3 for more details.

      <Example><![CDATA[
gap> I := InverseSemigroup([
>  PartialPerm([2, 3]), PartialPerm([2, 0, 3])]);;
gap> cong := SemigroupCongruenceByGeneratingPairs(I,
> [[PartialPerm([0, 1, 3]), PartialPerm([0, 1])],
>  [PartialPerm([]), PartialPerm([1, 2])]]);
<2-sided semigroup congruence over <inverse partial perm semigroup of 
 rank 3 with 2 generators> with 2 generating pairs>
gap> cong2 := AsInverseSemigroupCongruenceByKernelTrace(cong);
<semigroup congruence over <inverse partial perm semigroup 
 of size 19, rank 3 with 2 generators> with congruence pair (19,1)>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsInverseSemigroupCongruenceByKernelTrace">
  <ManSection>
    <Filt Name = "IsInverseSemigroupCongruenceByKernelTrace" Arg = "cong"
      Type = "Category"/>
    <Returns>
      <K>true</K> or <K>false</K>.</Returns>
    <Description>
      This category contains any inverse semigroup congruence <A>cong</A> which
      is represented internally by its kernel and trace.  The <Ref
        Func = "SemigroupCongruence"/> function may create an
      object of this category if its first argument <A>S</A> is an inverse
      semigroup and has sufficiently large size.  It can be treated
      like any other semigroup congruence object.
      <P/>

      See <Cite Key = "Howie1995aa"/> Section 5.3 for more details.  See also
      <Ref Func = "InverseSemigroupCongruenceByKernelTrace"/>.
 
      <Example><![CDATA[
gap> S := InverseSemigroup([
>  PartialPerm([4, 3, 1, 2]),
>  PartialPerm([1, 4, 2, 0, 3])],
>  rec(cong_by_ker_trace_threshold := 0));;
gap> cong := SemigroupCongruence(S, []);
<semigroup congruence over <inverse partial perm semigroup 
 of size 351, rank 5 with 2 generators> with congruence pair (24,24)>
gap> IsInverseSemigroupCongruenceByKernelTrace(cong);
true]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsInverseSemigroupCongruenceClassByKernelTrace">
  <ManSection>
    <Filt Name = "IsInverseSemigroupCongruenceClassByKernelTrace" Arg = "obj"
      Type = "Category"/>
    <Returns>
      <K>true</K> or <K>false</K>.
    </Returns>
    <Description>
      This category contains any congruence class which belongs to a congruence
      which is represented internally by its kernel and trace.  See <Ref
      Func = "InverseSemigroupCongruenceByKernelTrace"/>. <P/>

      See <Cite Key = "Howie1995aa"/> Section 5.3 for more details.

      <Example><![CDATA[
gap> I := InverseSemigroup([
>  PartialPerm([2, 3]), PartialPerm([2, 0, 3])],
> rec(cong_by_ker_trace_threshold := 0));;
gap> cong := SemigroupCongruence(I,
> [[PartialPerm([0, 1, 3]), PartialPerm([0, 1])],
>  [PartialPerm([]), PartialPerm([1, 2])]]);;
gap> class := EquivalenceClassOfElement(cong,
>                                      PartialPerm([1, 2], [2, 3]));;
gap> IsInverseSemigroupCongruenceClassByKernelTrace(class);
true]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="InverseSemigroupCongruenceByKernelTrace">
  <ManSection>
    <Func Name = "InverseSemigroupCongruenceByKernelTrace"
      Arg = "S, kernel, traceBlocks"/>
    <Returns>
      An inverse semigroup congruence by kernel and trace.
    </Returns>
    <Description>
      If <A>S</A> is an inverse semigroup, <A>kernel</A> is a subsemigroup of
      <A>S</A>, <A>traceBlocks</A> is a list of lists describing a congruence
      on the idempotents of <A>S</A>, and <M>(<A>kernel</A>, <A>trace</A>)</M>
      describes a valid congruence pair for <A>S</A> (see <Cite Key =
        "Howie1995aa"/> Section 5.3) then this function returns the semigroup
      congruence defined by that congruence pair. <P/>

      See also <Ref Attr = "KernelOfSemigroupCongruence"/> and
      <Ref Attr = "TraceOfSemigroupCongruence"/>.
 
      <Example><![CDATA[
gap> S := InverseSemigroup([
>   PartialPerm([2, 3]), PartialPerm([2, 0, 3])]);;
gap> kernel := InverseSemigroup([
>   PartialPerm([1, 0, 3]), PartialPerm([0, 2, 3]),
>   PartialPerm([1, 2]), PartialPerm([3]),
>   PartialPerm([2])]);;
gap> trace := [
>  [PartialPerm([0, 2, 3])],
>  [PartialPerm([1, 2])],
>  [PartialPerm([1, 0, 3])],
>  [PartialPerm([0, 0, 3]), PartialPerm([0, 2]),
>   PartialPerm([1]), PartialPerm([], [])]];;
gap> cong := InverseSemigroupCongruenceByKernelTrace(S, kernel, trace);
<semigroup congruence over <inverse partial perm semigroup of rank 3 
 with 2 generators> with congruence pair (13,4)>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="MinimumGroupCongruence">
  <ManSection>
    <Attr Name = "MinimumGroupCongruence" Arg = "S"/>
    <Returns>
      An inverse semigroup congruence by kernel and trace.
    </Returns>
    <Description>
      If <A>S</A> is an inverse semigroup, then this function returns the
      least congruence on <A>S</A> whose quotient is a group. <P/>

      <Example><![CDATA[
gap> S := InverseSemigroup([
>   PartialPerm([5, 2, 0, 0, 1, 4]),
>   PartialPerm([1, 4, 6, 3, 5, 0, 2])]);;
gap> cong := MinimumGroupCongruence(S);
<semigroup congruence over <inverse partial perm semigroup 
 of size 101, rank 7 with 2 generators> with congruence pair (59,1)>
gap> IsGroupAsSemigroup(S / cong);
true]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>
