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

<#GAPDoc Label="IsRZMSCongruenceByLinkedTriple">
  <ManSection>
    <Filt Name = "IsRMSCongruenceByLinkedTriple" Arg = "obj" Type = "category"/>
    <Filt Name = "IsRZMSCongruenceByLinkedTriple" Arg = "obj" Type = "category"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
      These categories describe a type of semigroup congruence over a Rees
      matrix or 0-matrix semigroup.  Externally, an object of this type may be
      used in the same way as any other object in the category <Ref
      Prop = "IsSemigroupCongruence" BookName = "ref"/> but it is represented
      internally by its <E>linked triple</E>, and certain functions may take
      advantage of this information to reduce computation times.<P/>

      An object of this type may be constructed with
      <C>RMSCongruenceByLinkedTriple</C> or <C>RZMSCongruenceByLinkedTriple</C>,
      or this representation may be selected automatically by <Ref
      Func = "SemigroupCongruence"/>.

      <Example><![CDATA[
gap> G := Group([(1, 4, 5), (1, 5, 3, 4)]);;
gap> mat := [[0, 0, (1, 4, 5), 0, 0, (1, 4, 3, 5)],
>            [0, (), 0, 0, (3, 5), 0],
>            [(), 0, 0, (3, 5), 0, 0]];;
gap> S := ReesZeroMatrixSemigroup(G, mat);;
gap> N := Group([(1, 4)(3, 5), (1, 5)(3, 4)]);;
gap> colBlocks := [[1], [2, 5], [3, 6], [4]];;
gap> rowBlocks := [[1], [2], [3]];;
gap> cong := RZMSCongruenceByLinkedTriple(S, N, colBlocks, rowBlocks);;
gap> IsRZMSCongruenceByLinkedTriple(cong);
true]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsRZMSCongruenceClassByLinkedTriple">
  <ManSection>
    <Filt Name = "IsRMSCongruenceClassByLinkedTriple" Arg = "obj"
      Type = "category"/>
    <Filt Name = "IsRZMSCongruenceClassByLinkedTriple" Arg = "obj"
      Type = "category"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
      These categories contain the congruence classes of a semigroup congruence
      of the categories <Ref Filt = "IsRMSCongruenceByLinkedTriple"/> and <Ref
      Filt = "IsRZMSCongruenceByLinkedTriple"/> respectively. <P/>

      An object of one of these types may be used in the same way as any other
      object in the category <Ref Filt = "IsCongruenceClass"/>,
      but the class is represented internally by information related
      to the congruence's <E>linked triple</E>, and certain functions may take
      advantage of this information to reduce computation times. <P/>

      <Example><![CDATA[
gap> G := Group([(1, 4, 5), (1, 5, 3, 4)]);;
gap> mat := [[0, 0, (1, 4, 5), 0, 0, (1, 4, 3, 5)],
>            [0, (), 0, 0, (3, 5), 0],
>            [(), 0, 0, (3, 5), 0, 0]];;
gap> S := ReesZeroMatrixSemigroup(G, mat);;
gap> N := Group([(1, 4)(3, 5), (1, 5)(3, 4)]);;
gap> colBlocks := [[1], [2, 5], [3, 6], [4]];;
gap> rowBlocks := [[1], [2], [3]];;
gap> cong := RZMSCongruenceByLinkedTriple(S, N, colBlocks, rowBlocks);;
gap> classes := EquivalenceClasses(cong);;
gap> IsRZMSCongruenceClassByLinkedTriple(classes[1]);
true]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="RZMSCongruenceByLinkedTriple">
  <ManSection>
    <Func Name = "RMSCongruenceByLinkedTriple"
      Arg = "S, N, colBlocks, rowBlocks"/>
    <Func Name = "RZMSCongruenceByLinkedTriple"
      Arg = "S, N, colBlocks, rowBlocks"/>
    <Returns>
      A Rees matrix or 0-matrix semigroup congruence by linked triple.
    </Returns>
    <Description>
      This function returns a semigroup congruence over the Rees matrix or
      0-matrix semigroup <A>S</A> corresponding to the linked triple (<A>N</A>,
      <A>colBlocks</A>, <A>rowBlocks</A>).  The argument <A>N</A> should be a
      normal subgroup of the underlying semigroup of <A>S</A>; <A>colBlocks</A>
      should be a partition of the columns of the matrix of <A>S</A>; and
      <A>rowBlocks</A> should be a partition of the rows of the matrix of
      <A>S</A>.  For example, if the matrix has 5 rows, then a possibility for
      <A>rowBlocks</A> might be <C>[[1, 3], [2, 5], [4]]</C>.<P/>

      If the arguments describe a valid linked triple on <A>S</A>, then an
      object in the category <C>IsRZMSCongruenceByLinkedTriple</C> is returned.
      This object can be used like any other semigroup congruence in
      &GAP;.<P/>

      If the arguments describe a triple which is not <E>linked</E> in the sense
      described above, then this function returns an error.
      <Example><![CDATA[
gap> G := Group([(1, 4, 5), (1, 5, 3, 4)]);;
gap> mat := [[0, 0, (1, 4, 5), 0, 0, (1, 4, 3, 5)],
>            [0, (), 0, 0, (3, 5), 0],
>            [(), 0, 0, (3, 5), 0, 0]];;
gap> S := ReesZeroMatrixSemigroup(G, mat);;
gap> N := Group([(1, 4)(3, 5), (1, 5)(3, 4)]);;
gap> colBlocks := [[1], [2, 5], [3, 6], [4]];;
gap> rowBlocks := [[1], [2], [3]];;
gap> cong := RZMSCongruenceByLinkedTriple(S, N, colBlocks, rowBlocks);;
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="RZMSCongruenceClassByLinkedTriple">
  <ManSection>
    <Oper Name = "RMSCongruenceClassByLinkedTriple"
	  Arg = "cong, nCoset, colClass, rowClass"/>
    <Oper Name = "RZMSCongruenceClassByLinkedTriple"
	  Arg = "cong, nCoset, colClass, rowClass"/>
    <Returns>
      A Rees matrix or 0-matrix semigroup congruence class by linked
      triple.
    </Returns>
    <Description>
      This operation returns one congruence class of the congruence
      <A>cong</A>, as defined by the other three parameters.<P/>

      The argument <A>cong</A> must be a Rees matrix or 0-matrix semigroup
      congruence by linked triple.  If the linked triple consists of the three
      parameters <C>N</C>, <C>colBlocks</C> and <C>rowBlocks</C>, then
      <A>nCoset</A> must be a right coset of <C>N</C>, <A>colClass</A> must be
      a positive integer corresponding to a position in the list
      <C>colBlocks</C>, and <A>rowClass</A> must be a positive integer
      corresponding to a position in the list <C>rowBlocks</C>.<P/>

      If the arguments are valid, an <C>IsRMSCongruenceClassByLinkedTriple</C>
      or <C>IsRZMSCongruenceClassByLinkedTriple</C> object is returned, which
      can be used like any other equivalence class in &GAP;.  Otherwise, an
      error is returned.
      <Example><![CDATA[
gap> G := Group([(1, 4, 5), (1, 5, 3, 4)]);;
gap> mat := [[0, 0, (1, 4, 5), 0, 0, (1, 4, 3, 5)],
>            [0, (), 0, 0, (3, 5), 0],
>            [(), 0, 0, (3, 5), 0, 0]];;
gap> S := ReesZeroMatrixSemigroup(G, mat);;
gap> N := Group([(1, 4)(3, 5), (1, 5)(3, 4)]);;
gap> colBlocks := [[1], [2, 5], [3, 6], [4]];;
gap> rowBlocks := [[1], [2], [3]];;
gap> cong := RZMSCongruenceByLinkedTriple(S, N, colBlocks, rowBlocks);;
gap> class := RZMSCongruenceClassByLinkedTriple(cong,
> RightCoset(N, (1, 5)), 2, 3);
<2-sided congruence class of (2,(3,4),3)>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsLinkedTriple">
  <ManSection>
    <Oper Name = "IsLinkedTriple" Arg = "S, N, colBlocks, rowBlocks"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
      This operation returns true if and only if the arguments (<A>N</A>,
      <A>colBlocks</A>, <A>rowBlocks</A>) describe a linked triple of
      the Rees matrix or 0-matrix semigroup <A>S</A>, as described above.
      <Example><![CDATA[
gap> G := Group([(1, 4, 5), (1, 5, 3, 4)]);;
gap> mat := [[0, 0, (1, 4, 5), 0, 0, (1, 4, 3, 5)],
>            [0, (), 0, 0, (3, 5), 0],
>            [(), 0, 0, (3, 5), 0, 0]];;
gap> S := ReesZeroMatrixSemigroup(G, mat);;
gap> N := Group([(1, 4)(3, 5), (1, 5)(3, 4)]);;
gap> colBlocks := [[1], [2, 5], [3, 6], [4]];;
gap> rowBlocks := [[1], [2], [3]];;
gap> IsLinkedTriple(S, N, colBlocks, rowBlocks);
true]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>
