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

<#GAPDoc Label="IsRMSIsoByTriple">
  <ManSection>
    <Filt Name = "IsRMSIsoByTriple" Type = "Category"/>
    <Filt Name = "IsRZMSIsoByTriple" Type = "Category"/>
    <Description>
      The isomorphisms between finite Rees matrix or 0-matrix semigroups
      <C>S</C> and <C>T</C> over groups <C>G</C> and <C>H</C>, respectively,
      specified by a triple consisting of:

      <Enum>

        <Item>
          an isomorphism of the underlying graph of <C>S</C> to the underlying
          graph of of <C>T</C>
        </Item>

        <Item>
          an isomorphism from <C>G</C> to <C>H</C>
        </Item>

        <Item>
          a function from <C>Rows(S)</C> union <C>Columns(S)</C> to <C>H</C>
        </Item>

      </Enum>

      belong to the categories <C>IsRMSIsoByTriple</C> and
      <C>IsRZMSIsoByTriple</C>.  Basic operators for such isomorphism are given
      in <Ref Subsect =
        "Operators for isomorphisms of Rees (0-)matrix semigroups"/>,
      and basic operations are:

      <Ref Attr = "Range" BookName = "ref"/>,
      <Ref Attr = "Source" BookName = "ref"/>,
      <Ref Oper = "ELM_LIST" Label = "for IsRMSIsoByTriple"/>,
      <Ref Func = "CompositionMapping" BookName = "ref"/>,
      <Ref Oper = "ImagesElm" Label = "for IsRMSIsoByTriple"/>,
      <Ref Oper = "ImagesRepresentative" Label = "for IsRMSIsoByTriple"/>,
      <Ref Attr = "InverseGeneralMapping" BookName = "ref"/>,
      <Ref Oper = "PreImagesRepresentative" BookName = "ref"/>,
      <Ref Prop = "IsOne" BookName = "ref"/>.

    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="RMSIsoByTriple">
  <ManSection>
    <Oper Name = "RMSIsoByTriple" Arg = "R1, R2, triple"/>
    <Oper Name = "RZMSIsoByTriple" Arg = "R1, R2, triple"/>
    <Returns>An isomorphism.</Returns>
    <Description>
      If <A>R1</A> and <A>R2</A> are isomorphic regular Rees 0-matrix semigroups
      whose underlying semigroups are groups then <C>RZMSIsoByTriple</C> returns
      the isomorphism between <A>R1</A> and <A>R2</A> defined by <A>triple</A>,
      which should be a list consisting of the following:

      <List>
        <Item>
          <C><A>triple</A>[1]</C> should be a permutation describing an
          isomorphism from the graph of <A>R1</A> to the graph of <A>R2</A>,
          i.e. it should satisfy
          <C>OnDigraphs(RZMSDigraph(<A>R1</A>), <A>triple</A>[1])
             = RZMSDigraph(<A>R2</A>)</C>.
        </Item>
        <Item>
          <C><A>triple</A>[2]</C> should be an isomorphism from the underlying
          group of <A>R1</A> to the underlying group of <A>R2</A> (see
          <Ref Attr="UnderlyingSemigroup"
               Label="for a Rees 0-matrix semigroup"
               BookName="ref"/>).
        </Item>
        <Item>
          <C><A>triple</A>[3]</C> should be a list of elements from the
          underlying group of <A>R2</A>.  If the
          <Ref Attr="Matrix" BookName="ref"/>
          of <A>R1</A> has <M>m</M> columns
          and <M>n</M> rows, then the list should have length <M>m + n</M>,
          where the first <M>m</M> entries should correspond to the columns of
          <A>R1</A>'s matrix, and the last <M>n</M> entries should correspond to
          the rows.  These column and row entries should correspond to the
          <M>u_i</M> and <M>v_\lambda</M> elements in Theorem 3.4.1 of
          <Cite Key = "Howie1995aa"/>.
        </Item>
      </List>

      If <A>triple</A> describes a valid isomorphism from <A>R1</A> to <A>R2</A>
      then this will return an object in the category
      <Ref Filt="IsRZMSIsoByTriple"/>; otherwise an error will be returned. <P/>

      If <A>R1</A> and <A>R2</A> are instead Rees matrix semigroups (without
      zero) then <C>RMSIsoByTriple</C> should be used instead.  This operation
      is used in the same way, but it should be noted that since an RMS's graph
      is a complete bipartite graph, <C><A>triple</A>[1]</C> can be any
      permutation on <C>[1 .. m + n]</C>, so long as no point in <C>[1 .. m]</C>
      is mapped to a point in <C>[m + 1 .. m + n]</C>. <P/>

      <Example><![CDATA[
gap> g := SymmetricGroup(3);;
gap> mat := [[0, 0, (1, 3)], [(1, 2, 3), (), (2, 3)], [0, 0, ()]];;
gap> R := ReesZeroMatrixSemigroup(g, mat);;
gap> id := IdentityMapping(g);;
gap> g_elms_list := [(), (), (), (), (), ()];;
gap> RZMSIsoByTriple(R, R, [(), id, g_elms_list]);
((), IdentityMapping( SymmetricGroup( [ 1 .. 3 ] ) ),
[ (), (), (), (), (), () ])
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="ELM_LIST">
  <ManSection>
    <Oper Name = "ELM_LIST" Label = "for IsRMSIsoByTriple"
      Arg = "map, pos"/>
    <Returns>
      A component of an isomorphism of Rees (0-)matrix semigroups by triple.
    </Returns>
    <Description>
      <C>ELM_LIST(<A>map</A>, <A>i</A>)</C> returns the <C>i</C>th component of
      the Rees (0-)matrix semigroup isomorphism by triple <A>map</A> when
      <C>i = 1, 2, 3</C>.
      <P/>

      The components of an isomorphism of Rees (0-)matrix semigroups by triple
      are:
        <Enum>
          <Item>
            An isomorphism of the underlying graphs of the source and range of
            <A>map</A>, respectively.
          </Item>

          <Item>
            An isomorphism of the underlying groups of the source and range of
            <A>map</A>, respectively.
          </Item>

          <Item>
            An function from the union of the rows and columns of the source of
            <A>map</A> to the underlying group of the range of <A>map</A>.
          </Item>
        </Enum>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="CompositionMapping2">
  <ManSection>
    <Oper Name = "CompositionMapping2" Label = "for IsRMSIsoByTriple"
      Arg = "map1, map2"/>
    <Oper Name = "CompositionMapping2" Label = "for IsRZMSIsoByTriple"
      Arg = "map1, map2"/>
    <Returns>
      A Rees (0-)matrix semigroup by triple.
    </Returns>
    <Description>
      If <A>map1</A> and <A>map2</A> are isomorphisms of Rees matrix or
      0-matrix semigroups specified by triples and the range of <A>map2</A> is
      contained in the source of <A>map1</A>, then
      <C>CompositionMapping2(<A>map1</A>, <A>map2</A>)</C> returns the
      isomorphism from <C>Source(<A>map2</A>)</C> to <C>Range(<A>map1</A>)</C>
      specified by the triple with components:

      <Enum>
        <Item>
          <C><A>map1</A>[1] * <A>map2</A>[1]</C>
        </Item>

        <Item>
          <C><A>map1</A>[2] * <A>map2</A>[2]</C>
        </Item>

        <Item>
          the componentwise product of <C><A>map1</A>[1] * <A>map2</A>[3]</C>
          and  <C><A>map1</A>[3] * <A>map2</A>[2]</C>.
        </Item>
      </Enum>
      <Example><![CDATA[
gap> R := ReesZeroMatrixSemigroup(Group([(1, 2, 3, 4)]),
> [[(1, 3)(2, 4), (1, 4, 3, 2), (), (1, 2, 3, 4), (1, 3)(2, 4), 0],
>  [(1, 4, 3, 2), 0, (), (1, 4, 3, 2), (1, 2, 3, 4), (1, 2, 3, 4)],
>  [(), (), (1, 4, 3, 2), (1, 2, 3, 4), 0, (1, 2, 3, 4)],
>  [(1, 2, 3, 4), (1, 4, 3, 2), (1, 2, 3, 4), 0, (), (1, 2, 3, 4)],
>  [(1, 3)(2, 4), (1, 2, 3, 4), 0, (), (1, 4, 3, 2), (1, 2, 3, 4)],
>  [0, (1, 2, 3, 4), (1, 2, 3, 4), (1, 2, 3, 4), (1, 2, 3, 4), ()]]);
<Rees 0-matrix semigroup 6x6 over Group([ (1,2,3,4) ])>
gap> G := AutomorphismGroup(R);;
gap> G.2;
((), IdentityMapping( Group( [ (1,2,3,4) ] ) ),
[ (), (), (), (), (), (), (), (), (), (), (), () ])
gap> G.3;
(( 2, 4)( 3, 5)( 8,10)( 9,11), GroupHomomorphismByImages( Group(
[ (1,2,3,4) ] ), Group( [ (1,2,3,4) ] ), [ (1,2,3,4) ],
[ (1,2,3,4) ] ), [ (), (1,3)(2,4), (1,3)(2,4), (1,3)(2,4),
  (1,3)(2,4), (1,3)(2,4), (), (1,3)(2,4), (1,3)(2,4), (1,3)(2,4),
  (1,3)(2,4), (1,3)(2,4) ])
gap> CompositionMapping2(G.2, G.3);
(( 2, 4)( 3, 5)( 8,10)( 9,11), GroupHomomorphismByImages( Group(
[ (1,2,3,4) ] ), Group( [ (1,2,3,4) ] ), [ (1,2,3,4) ],
[ (1,2,3,4) ] ), [ (), (1,3)(2,4), (1,3)(2,4), (1,3)(2,4),
  (1,3)(2,4), (1,3)(2,4), (), (1,3)(2,4), (1,3)(2,4), (1,3)(2,4),
  (1,3)(2,4), (1,3)(2,4) ])]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="ImagesElm">
  <ManSection>
    <Oper Name = "ImagesElm" Label = "for IsRMSIsoByTriple" Arg = "map, pt"/>
    <Oper Name = "ImagesRepresentative" Label = "for IsRMSIsoByTriple"
      Arg = "map, pt"/>
    <Returns>
      An element of a Rees (0-)matrix semigroup or a list containing such an
      element.
    </Returns>

    <Description>
      If <A>map</A> is an isomorphism of Rees matrix or 0-matrix semigroups
      specified by a triple and <A>pt</A> is an element of the source of
      <A>map</A>, then <C>ImagesRepresentative(<A>map</A>, <A>pt</A>) =
      <A>pt</A> ^ <A>map</A></C> returns the image of <A>pt</A> under
      <A>map</A>.
      <P/>

      The image of <A>pt</A> under <A>map</A> of <C>Range(<A>map</A>)</C> is the
      element with components:

      <Enum>
        <Item>
          <C><A>pt</A>[1] ^ <A>map</A>[1]</C>
        </Item>
        <Item>
          <C>(<A>pt</A>[1] ^ <A>map</A>[3]) * (<A>pt</A>[2] ^ <A>map</A>[2])
            * (<A>pt</A>[3] ^ <A>map</A>[3]) ^ -1</C>
        </Item>
        <Item>
          <C><A>pt</A>[3] ^ <A>map</A>[1]</C>.
        </Item>
      </Enum>

      <C>ImagesElm(<A>map</A>, <A>pt</A>)</C> simply returns
      <C>[ImagesRepresentative(<A>map</A>, <A>pt</A>)]</C>.

      <Example><![CDATA[
gap> R := ReesZeroMatrixSemigroup(Group([(2, 8), (2, 8, 6)]),
> [[0, (2, 8), 0, 0, 0, (2, 8, 6)],
>  [(), 0, (2, 8, 6), (2, 6), (2, 6, 8), 0],
>  [(2, 8, 6), 0, (2, 6, 8), (2, 8), (), 0],
>  [(2, 8, 6), 0, (2, 6, 8), (2, 8), (), 0],
>  [0, (2, 8, 6), 0, 0, 0, (2, 8)],
>  [(2, 8, 6), 0, (2, 6, 8), (2, 8), (), 0]]);
<Rees 0-matrix semigroup 6x6 over Group([ (2,8), (2,8,6) ])>
gap> map := RZMSIsoByTriple(R, R,
> [(), IdentityMapping(Group([(2, 8), (2, 8, 6)])),
> [(), (2, 6, 8), (), (), (), (2, 8, 6),
>  (2, 8, 6), (), (), (), (2, 6, 8), ()]]);;
gap> ImagesElm(map, RMSElement(R, 1, (2, 8), 2));
[ (1,(2,8),2) ]]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="CanonicalReesZeroMatrixSemigroup">
  <ManSection>
    <Attr Name = "CanonicalReesZeroMatrixSemigroup" Arg = "S"/>
    <Attr Name = "CanonicalReesMatrixSemigroup" Arg = "S"/>

    <Returns>
      A Rees zero matrix semigroup.
    </Returns>

    <Description>
      If <A>S</A> is a Rees 0-matrix semigroup then
      <C>CanonicalReesZeroMatrixSemigroup</C> returns an isomorphic Rees
      0-matrix semigroup <C>T</C> with the same
      <Ref Attr="UnderlyingSemigroup" Label="for a Rees 0-matrix semigroup"
        BookName="ref"/>
      as <A>S</A> but the
      <Ref Attr="Matrix" BookName="ref"/>
      of <C>T</C> has been canonicalized.  The output
      <C>T</C> is canonical in the sense that for any two inputs
      which are isomorphic Rees zero matrix semigroups the output of this
      function is the same.<P/>
      <C>CanonicalReesMatrixSemigroup</C> works the same but for Rees matrix
      semigroups.

      <Example><![CDATA[
gap> S := ReesZeroMatrixSemigroup(SymmetricGroup(3),
> [[(), (1, 3, 2)], [(), ()]]);;
gap> T := CanonicalReesZeroMatrixSemigroup(S);
<Rees 0-matrix semigroup 2x2 over Sym( [ 1 .. 3 ] )>
gap> Matrix(S);
[ [ (), (1,3,2) ], [ (), () ] ]
gap> Matrix(T);
[ [ (), () ], [ (), (1,2,3) ] ]]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>
