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

<#GAPDoc Label="Normalizer">
  <ManSection>
    <Oper Name="Normalizer" Arg="G, S[, opts]" 
      Label="for a perm group, semigroup, record"/>
    <Oper Name="Normalizer" Arg="S[, opts]" Label="for a semigroup, record"/>
    <Returns>A permutation group.</Returns>
    <Description> 
      In its first form, this function returns the normalizer of the
      transformation, partial perm, or bipartition semigroup <A>S</A> in the
      permutation group <A>G</A>.  In its second form, the normalizer of
      <A>S</A> in the symmetric group on <C>[1..n]</C> where <C>n</C> is the
      degree of <A>S</A> is returned.<P/>
      
      The <B>normalizer</B> of a transformation semigroup <A>S</A> in a
      permutation group <A>G</A> in the subgroup <C>H</C> of <A>G</A> consisting
      of those elements in <C>g</C> in <A>G</A> conjugating <A>S</A> to
      <A>S</A>, i.e.  <C><A>S</A>^g=<A>S</A></C>. <P/>
      
      Analogous definitions can be given for a partial perm and bipartition
      semigroups.<P/>

      The method used by this operation is based on Section 3 in 
      <Cite Key="Araujo2010aa"/>.<P/>

      The optional final argument <A>opts</A> allows you to specify various
      options, which determine how the normalizer is calculated. The values of
      these options can dramatically change the time it takes for this operation
      to complete. In different situations, different options give the best
      performance. <P/>

      The argument <A>opts</A> should be a record, and the available options are:
      
      <List>
        <Mark>random</Mark>
        <Item>
          If this option has the value <K>true</K> and the &genss; package is
          loaded, then the non-deterministic algorithms in &genss; are used in 
          <C>Normalizer</C>. So, there is some chance that <C>Normalizer</C>
          will return an incorrect result in this case, but these methods can
          also be much faster than the deterministic algorithms which are used
          if this option is <K>false</K>.  <P/>

          If &genss; is not loaded, then this option is ignored. <P/> 
          
          The default value for this option is <K>false</K>.
        </Item>
          
        <Mark>lambdastab</Mark>
        <Item>
          If this option has the value <K>true</K>, then <C>Normalizer</C>
          initially finds the setwise stabilizer of the images or right blocks
          of the semigroup <A>S</A>. Sometimes this improves the performance of
          <C>Normalizer</C> and sometimes it does not. If this option in
          <K>false</K>, then this setwise stabilizer is not found.  <P/>

          The default value for this option is <K>true</K>.
        </Item>

        <Mark>rhostab</Mark>
        <Item>
          If this option has the value <K>true</K>, then <C>Normalizer</C>
          initially finds the setwise stabilizer of the kernels, domains, or
          left blocks of the semigroup <A>S</A>. Sometimes this improves the
          performance of <C>Normalizer</C> and sometimes it does not.  If this
          option is <K>false</K>, the this setwise stabilizer is not found. <P/>

          If <A>S</A> is an inverse semigroup, then this option is ignored.<P/>

          The default value for this option is <K>true</K>.
        </Item>
      </List> 

      <Log><![CDATA[
gap> S:=BrauerMonoid(8);
<regular bipartition monoid of degree 8 with 3 generators>
gap> StructureDescription(Normalizer(S));
"S8"
gap> S:=InverseSemigroup( 
> PartialPerm( [ 1, 2, 3, 4, 5 ], [ 2, 5, 6, 3, 8 ] ), 
> PartialPerm( [ 1, 2, 4, 7, 8 ], [ 3, 6, 2, 5, 7 ] ) );;
gap> Normalizer(S, rec(random:=true, lambdastab:=false));
#I  Have 33389 points.
#I  Have 40136 points in new orbit.
Group(())]]></Log>

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