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

<#GAPDoc Label="OnMultiplicationTable">
<ManSection>
  <Oper Name = "OnMultiplicationTable" Arg = "table, p"/>
  <Returns>
    A multiplication table.
  </Returns>
  <Description>
    If <A>table</A> is a multiplication table of a semigroup and the second
    argument <A>p</A> is a permutation of 
    <C>[1 .. Length(<A>table</A>)]</C>, then this operation returns a
    multiplication table of a semigroup isomorphic to that defined by
    <A>table</A> where the elements <C>[1 .. Length(<A>table</A>)]</C> are
    relabelled according to <A>p</A>.

    <Example><![CDATA[
gap> table := [[1, 1, 3, 4, 5, 6, 7, 8], 
>              [1, 1, 3, 4, 5, 6, 7, 8], 
>              [1, 1, 3, 4, 5, 6, 7, 8], 
>              [1, 3, 3, 4, 5, 6, 7, 8], 
>              [5, 5, 6, 7, 5, 6, 7, 8], 
>              [5, 5, 6, 7, 5, 6, 7, 8], 
>              [5, 6, 6, 7, 5, 6, 7, 8], 
>              [5, 6, 6, 7, 5, 6, 7, 8]];;
gap> p := (1, 2, 3, 4)(10, 11, 12);;
gap> OnMultiplicationTable(table, p);
[ [ 1, 2, 4, 4, 5, 6, 7, 8 ], [ 1, 2, 2, 4, 5, 6, 7, 8 ], 
  [ 1, 2, 2, 4, 5, 6, 7, 8 ], [ 1, 2, 2, 4, 5, 6, 7, 8 ], 
  [ 7, 5, 5, 6, 5, 6, 7, 8 ], [ 7, 5, 5, 6, 5, 6, 7, 8 ], 
  [ 7, 5, 6, 6, 5, 6, 7, 8 ], [ 7, 5, 6, 6, 5, 6, 7, 8 ] ]]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="CanonicalMultiplicationTablePerm">
<ManSection>
  <Attr Name = "CanonicalMultiplicationTablePerm" Arg = "S"/>
  <Returns>
    A permutation.
  </Returns>
  <Description>
    This function returns a permutation <C>p</C> such that 
    <C>OnMultiplicationTable(MultiplicationTable(<A>S</A>), p);</C>
    equals <C>CanonicalMultiplicationTable(<A>S</A>)</C>. <P/>

    See <Ref Attr="CanonicalMultiplicationTable"/> for more details.<P/>
    
    <C>CanonicalMultiplicationTablePerm</C> uses the machinery for canonical
      labelling of vertex coloured digraphs in &BLISS; via 
    <Ref Oper="BlissCanonicalLabelling" Label="for a digraph and a list"
      BookName="digraphs"/>.<P/>

    <Example><![CDATA[
gap> S := Semigroup(
> Bipartition([[1, 2, 3, -1, -3], [-2]]),
> Bipartition([[1, 2, 3, -1], [-2], [-3]]),
> Bipartition([[1, 2, 3], [-1], [-2, -3]]),
> Bipartition([[1, 2, -1], [3, -2], [-3]]));;
gap> Size(S);
8
gap> CanonicalMultiplicationTablePerm(S);
(1,5,8,3,6,7,2,4)]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="CanonicalMultiplicationTable">
  <ManSection>
    <Attr Name = "CanonicalMultiplicationTable" Arg = "S"/>
    <Returns>
      A canonical multiplication table (up to isomorphism) of a semigroup.
    </Returns>
    <Description>
      This function returns a multiplication table of a semigroup
      isomorphic to the semigroup <A>S</A>. <C>CanonicalMultiplicationTable</C>
      returns a multiplication that is canonical, in the sense that if two
      semigroups <C>S</C> and <C>T</C> are isomorphic, then the return values
      of <C>CanonicalMultiplicationTable</C> are equal. <P/>

      <C>CanonicalMultiplicationTable</C> uses the machinery for canonical
        labelling of vertex coloured digraphs in &BLISS; via 
      <Ref Oper="BlissCanonicalLabelling" Label="for a digraph and a list"
        BookName="digraphs"/>.<P/>

      The multiplication table returned by this function is the result of 
      <C>OnMultiplicationTable(MultiplicationTable(<A>S</A>),
        CanonicalMultiplicationTablePerm(<A>S</A>));</C><P/>

      Note that the performance of <C>CanonicalMultiplicationTable</C> is
        vastly superior to that of <C>SmallestMultiplicationTable</C>.<P/>

      See also: <Ref Attr= "CanonicalMultiplicationTablePerm"/> and 
      <Ref Oper="OnMultiplicationTable"/>.

      <Example><![CDATA[
gap> S := Semigroup(
> Bipartition([[1, 2, 3, -1, -3], [-2]]),
> Bipartition([[1, 2, 3, -1], [-2], [-3]]),
> Bipartition([[1, 2, 3], [-1], [-2, -3]]),
> Bipartition([[1, 2, -1], [3, -2], [-3]]));;
gap> Size(S);
8
gap> CanonicalMultiplicationTable(S);
[ [ 1, 2, 2, 8, 1, 2, 7, 8 ], [ 1, 2, 2, 8, 1, 2, 7, 8 ], 
  [ 1, 2, 6, 4, 5, 6, 7, 8 ], [ 1, 2, 5, 4, 5, 6, 7, 8 ], 
  [ 1, 2, 6, 4, 5, 6, 7, 8 ], [ 1, 2, 6, 4, 5, 6, 7, 8 ], 
  [ 1, 2, 1, 8, 1, 2, 7, 8 ], [ 1, 2, 1, 8, 1, 2, 7, 8 ] ]]]></Example>
    </Description>
  </ManSection>
  <#/GAPDoc>

<#GAPDoc Label="SmallestMultiplicationTable">
  <ManSection>
    <Attr Name = "SmallestMultiplicationTable" Arg = "S"/>
    <Returns>
      The lex-least multiplication table of a semigroup.
    </Returns>
    <Description>
      This function returns the lex-least multiplication table of a semigroup
      isomorphic to the semigroup <A>S</A>. <C>SmallestMultiplicationTable</C>
      returns the lex-least multiplication of any semigroup isomoprhic to
      <A>S</A>.

      Due to the high complexity of computing the smallest multiplication table
      of a semigroup, this function only performs well for semigroups with
      at most approximately 50 elements.<P/>

      <C>SmallestMultiplicationTable</C> is based on the function
      <Ref Attr = "IdSmallSemigroup" BookName = "Smallsemi"/> by Andreas
        Distler.<P/>

      From Version 3.3.0 of &SEMIGROUPS; this attribute is computed using
        <Ref Func="MinimalImage" BookName = "images"/> from the
        the &IMAGES; package.

      See also: <Ref Attr= "CanonicalMultiplicationTable"/>.

      <Example><![CDATA[
gap> S := Semigroup(
> Bipartition([[1, 2, 3, -1, -3], [-2]]),
> Bipartition([[1, 2, 3, -1], [-2], [-3]]),
> Bipartition([[1, 2, 3], [-1], [-2, -3]]),
> Bipartition([[1, 2, -1], [3, -2], [-3]]));;
gap> Size(S);
8
gap> SmallestMultiplicationTable(S);
[ [ 1, 1, 3, 4, 5, 6, 7, 8 ], [ 1, 1, 3, 4, 5, 6, 7, 8 ], 
  [ 1, 1, 3, 4, 5, 6, 7, 8 ], [ 1, 3, 3, 4, 5, 6, 7, 8 ], 
  [ 5, 5, 6, 7, 5, 6, 7, 8 ], [ 5, 5, 6, 7, 5, 6, 7, 8 ], 
  [ 5, 6, 6, 7, 5, 6, 7, 8 ], [ 5, 6, 6, 7, 5, 6, 7, 8 ] ]]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsIsomorphicSemigroup">
  <ManSection>
    <Oper Name = "IsIsomorphicSemigroup" Arg = "S, T"/>
    <Returns>
      <K>true</K> or <K>false</K>.
    </Returns>
    <Description>
      If <A>S</A> and <A>T</A> are semigroups, then this operation attempts
      to determine whether <A>S</A> and <A>T</A> are isomorphic semigroups by
      using the operation <Ref Oper = "IsomorphismSemigroups" />.  If
      <C>IsomorphismSemigroups(<A>S</A>, <A>T</A>)</C> returns an isomorphism,
      then <C>IsIsomorphicSemigroup(<A>S</A>, <A>T</A>)</C> returns <K>true</K>,
      while if <C>IsomorphismSemigroups(<A>S</A>, <A>T</A>)</C> returns
      <K>fail</K>, then <C>IsIsomorphicSemigroup(<A>S</A>, <A>T</A>)</C> returns
      <K>false</K>.<P/>

        Note that in some cases, at present, there is no
      method for determining whether <A>S</A> is isomorphic to <A>T</A>, even
      if it is obvious to the user whether or not <A>S</A> and <A>T</A> are
      isomorphic. There are plans to improve this in the future. <P/>

      <Example><![CDATA[
gap> S := Semigroup(PartialPerm([1, 2, 4], [1, 3, 5]),
>                   PartialPerm([1, 3, 5], [1, 2, 4]));;
gap> T := AsSemigroup(IsTransformationSemigroup, S);;
gap> IsIsomorphicSemigroup(S, T);
true
gap> IsIsomorphicSemigroup(FullTransformationMonoid(4),
> PartitionMonoid(4));
false]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsomorphismSemigroups">
  <ManSection>
    <Oper Name = "IsomorphismSemigroups" Arg = "S, T"/>
    <Returns>
      An isomorphism, or <K>fail</K>.
    </Returns>
    <Description>
      This operation attempts to find an isomorphism from the semigroup <A>S</A>
      to the semigroup <A>T</A>. If it finds one, then it is returned, and if
      not, then <K>fail</K> is returned. <P/>

      <C>IsomorphismSemigroups</C> uses the machinery for finding isomorphisms
        between vertex coloured digraphs in &BLISS; via 
      <Ref Oper="IsomorphismDigraphs" 
           Label="for digraphs and homogeneous lists"
           BookName="digraphs"/> using digraphs constructed from the
        multiplication tables of <A>S</A> and <A>T</A>.
      <P/>

      Note that finding an isomorphism between two semigroups is difficult, and
      may not be possible for semigroups whose size exceeds a few hundred 
      elements.  On the other hand, <C>IsomorphismSemigroups</C> may be
      able deduce that <A>S</A> and <A>T</A> are not isomorphic by finding
      that some of their semigroup-theoretic properties differ.

      <Example><![CDATA[
gap> S := RectangularBand(IsTransformationSemigroup, 4, 5);
<regular transformation semigroup of size 20, degree 9 with 5 
 generators>
gap> T := RectangularBand(IsBipartitionSemigroup, 4, 5);
<regular bipartition semigroup of size 20, degree 3 with 5 generators>
gap> IsomorphismSemigroups(S, T) <> fail;
true
gap> D := DClass(FullTransformationMonoid(5),
>                Transformation([1, 2, 3, 4, 1]));;
gap> S := PrincipalFactor(D);;
gap> StructureDescription(UnderlyingSemigroup(S));
"S4"
gap> S;
<Rees 0-matrix semigroup 10x5 over S4>
gap> D := DClass(PartitionMonoid(5),
> Bipartition([[1], [2, -2], [3, -3], [4, -4], [5, -5], [-1]]));;
gap> T := PrincipalFactor(D);;
gap> StructureDescription(UnderlyingSemigroup(T));
"S4"
gap> T;
<Rees 0-matrix semigroup 15x15 over S4>
gap> IsomorphismSemigroups(S, T);
fail
gap> I := SemigroupIdeal(FullTransformationMonoid(5),
>                        Transformation([1, 1, 2, 3, 4]));;
gap> T := PrincipalFactor(DClass(I, I.1));;
gap> StructureDescription(UnderlyingSemigroup(T));
"S4"
gap> T;
<Rees 0-matrix semigroup 10x5 over S4>
gap> IsomorphismSemigroups(S, T) <> fail;
true]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>
  
<#GAPDoc Label="AutomorphismGroup">
  <ManSection>
    <Oper Name = "AutomorphismGroup" Arg = "S" Label="for a semigroup"/>
    <Returns>
      A group.
    </Returns>
    <Description>
      This operation returns the group of automorphisms of the semigroup <A>S</A>. 

      <C>AutomorphismGroup</C> uses &BLISS; via  
      <Ref Oper="AutomorphismGroup" 
           Label="for a digraph and a homogeneous list"
           BookName="digraphs"/> using a vertex coloured digraph constructed
      from the multiplication table of <A>S</A>. Consequently, this method is
      only really feasible for semigroups whose size does not exceed a few hundred elements.
      <P/>
      <Example><![CDATA[
gap> S := RectangularBand(IsTransformationSemigroup, 4, 5);
<regular transformation semigroup of size 20, degree 9 with 5 
 generators>
gap> StructureDescription(AutomorphismGroup(S));
"S4 x S5"]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>
