#############################################################################
##
#W  maximal.xml
#Y  Copyright (C) 2013-16                                James D. Mitchell
##                                                          Wilf A. Wilson
##
##  Licensing information can be found in the README file of this package.
##
#############################################################################
##

<#GAPDoc Label="MaximalSubsemigroups">
<ManSection>
  <Attr Name = "MaximalSubsemigroups" Arg = "S" Label="for a finite semigroup"/>
  <Oper Name = "MaximalSubsemigroups" Arg = "S, opts"
    Label="for a finite semigroup and a record"/>
  <Returns>
    The maximal subsemigroups of <A>S</A>.
  </Returns>
  <Description>
    If <A>S</A> is a finite semigroup, then the attribute
    <C>MaximalSubsemigroups</C> returns a list of the non-empty maximal
    subsemigroups of <A>S</A>.  The methods used by <C>MaximalSubsemigroups</C>
    are based on <Cite Key="Graham1968aa"/>, and are described in
    <Cite Key="Donoven2018aa"/>.

    <P/>

    It is computationally expensive to search for the maximal subsemigroups of a
    semigroup, and so computations involving <C>MaximalSubsemigroups</C> may be
    very lengthy. A substantial amount of information on the progress of
    <C>MaximalSubsemigroups</C> is provided through the info class <Ref
      InfoClass="InfoSemigroups"/>, with increasingly detailed information given
    at levels 1, 2, and 3.

    <P/>

    The behaviour of <C>MaximalSubsemigroups</C> can be altered via the second
    argument <A>opts</A>, which should be a record. The optional
    components of <A>opts</A> are:

    <List>

      <Mark>gens (a boolean)</Mark>
      <Item>
        If <C><A>opts</A>.gens</C> is <K>false</K> or unspecified, then the
        maximal subsemigroups themselves are returned and not just generating
        sets for these subsemigroups.

        <P/>

        It can be more computationally expensive to return the generating sets
        for the maximal subsemigroups, than to return the maximal subsemigroups
        themselves.
      </Item>

      <Mark>contain (a list)</Mark>
      <Item>
        If <C><A>opts</A>.contain</C> is duplicate-free list of elements of
        <A>S</A>, then <C>MaximalSubsemigroups</C> will search for the maximal
        subsemigroups of <A>S</A> which contain those elements.
      </Item>

      <Mark>D (a &D;-class)</Mark>
      <Item>
        For a maximal subsemigroup <C>M</C> of a finite semigroup <A>S</A>,
        there exists a unique &D;-class which contains the complement of
        <C>M</C> in <A>S</A>. In other words, the elements of <A>S</A> which
        <C>M</C> lacks are contained in a unique &D;-class.

        <P/>

        If <C><A>opts</A>.D</C> is a &D;-class of <A>S</A>, then
        <C>MaximalSubsemigroups</C> will search exclusively for those maximal
        subsemigroups of <A>S</A> whose complement is contained in
        <C><A>opts</A>.D</C>.
      </Item>

      <Mark>types (a list)</Mark>
      <Item>
        <E>This option is relevant only if <A>S</A> is a regular Rees
          (0-)matrix semigroup over a group.</E>
        <P/>

        As described at the start of this subsection, <Ref Sect =
          "Computing maximal subsemigroups" />, a maximal subsemigroup of a
        regular Rees (0-)matrix semigroup over a group is one of 6 possible
        types.
        <P/>

        If <A>S</A> is a regular Rees (0-)matrix semigroup over a group and
        <C><A>opts</A>.types</C> is a subset of <C>[1 .. 6]</C>, then
        <C>MaximalSubsemigroups</C> will search for those maximal subsemigroups
        of <A>S</A> of the types enumerated by <C><A>opts</A>.types</C>.
        <P/>

        The default value for this option is <C>[1 .. 6]</C> (i.e. no
        restriction).
      </Item>
    </List>
  <Example><![CDATA[
gap> S := FullTransformationSemigroup(3);
<full transformation monoid of degree 3>
gap> MaximalSubsemigroups(S);
[ <transformation semigroup of degree 3 with 7 generators>, 
  <transformation semigroup of degree 3 with 7 generators>, 
  <transformation semigroup of degree 3 with 7 generators>, 
  <transformation semigroup of degree 3 with 7 generators>, 
  <transformation monoid of degree 3 with 5 generators> ]
gap> MaximalSubsemigroups(S,
> rec(gens := true, D := DClass(S, Transformation([2, 2, 3]))));
[ [ Transformation( [ 1, 1, 1 ] ), Transformation( [ 3, 3, 3 ] ), 
      Transformation( [ 2, 2, 2 ] ), IdentityTransformation, 
      Transformation( [ 2, 3, 1 ] ), Transformation( [ 2, 1 ] ) ] ]
gap> MaximalSubsemigroups(S,
> rec(contain := [Transformation([2, 3, 1])]));
[ <transformation semigroup of degree 3 with 7 generators>, 
  <transformation monoid of degree 3 with 5 generators> ]
gap> R := PrincipalFactor(
> DClass(FullTransformationMonoid(4), Transformation([2, 2])));
<Rees 0-matrix semigroup 6x4 over Group([ (2,3,4), (2,4) ])>
gap> MaximalSubsemigroups(R, rec(types := [5],
>   contain := [RMSElement(R, 1, (), 1),
>               RMSElement(R, 1, (2, 3), 2)]));
[ <subsemigroup of 6x4 Rees 0-matrix semigroup with 10 generators>, 
  <subsemigroup of 6x4 Rees 0-matrix semigroup with 10 generators>, 
  <subsemigroup of 6x4 Rees 0-matrix semigroup with 10 generators>, 
  <subsemigroup of 6x4 Rees 0-matrix semigroup with 10 generators> ]]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="NrMaximalSubsemigroups">
<ManSection>
  <Attr Name = "NrMaximalSubsemigroups" Arg = "S" />
  <Returns>
    The number of maximal subsemigroups of <A>S</A>.
  </Returns>
  <Description>
    If <A>S</A> is a finite semigroup, then <C>NrMaximalSubsemigroups</C>
    returns the number of non-empty maximal subsemigroups of <A>S</A>.  The
    methods used by <C>MaximalSubsemigroups</C> are based on <Cite
      Key="Graham1968aa"/>, and are described in <Cite Key="Donoven2018aa"/>.

    <P/>

    It can be significantly faster to find the number of maximal subsemigroups
    of a semigroup than to find the maximal subsemigroups themselves.

    <P/>

    Unless the maximal subsemigroups of <A>S</A> are already known, the command
    <C>NrMaximalSubsemigroups(<A>S</A>)</C> simply calls the command
    <C>MaximalSubsemigroups(<A>S</A>, rec(number := true))</C>.

    <P/>

    For more information about searching for maximal subsemigroups of a finite
    semigroup in the &SEMIGROUPS; package, and for information about the options
    available to alter the search, see <Ref Oper="MaximalSubsemigroups"
      Label="for a finite semigroup and a record"/>. By supplying the additional
    option <C><A>opts</A>.number :=</C> <K>true</K>, the number of maximal
    subsemigroups will be returned rather than the subsemigroups themselves.

  <Example><![CDATA[
gap> S := FullTransformationSemigroup(3);
<full transformation monoid of degree 3>
gap> NrMaximalSubsemigroups(S);
5
gap> S := RectangularBand(3, 4);;
gap> NrMaximalSubsemigroups(S);
7
gap> R := PrincipalFactor(
> DClass(FullTransformationMonoid(4), Transformation([2, 2])));
<Rees 0-matrix semigroup 6x4 over Group([ (2,3,4), (2,4) ])>
gap> MaximalSubsemigroups(R, rec(number := true, types := [3, 4]));
10]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsMaximalSubsemigroup">
<ManSection>
  <Oper Name = "IsMaximalSubsemigroup" Arg = "S, T"/>
  <Returns>
    <K>true</K> or <K>false</K>.
  </Returns>
  <Description>
    If <A>S</A> and <A>T</A> are semigroups, then <C>IsMaximalSubsemigroup</C>
    returns <K>true</K> if and only if <A>T</A> is a maximal subsemigroup of
    <A>S</A>.
    <P/>

    A <E>maximal subsemigroup</E> of <A>S</A> is a proper subsemigroup of
    <A>S</A> which is contained in no other proper subsemigroup of <A>S</A>.

    <Example><![CDATA[
gap> S := ZeroSemigroup(2);;
gap> IsMaximalSubsemigroup(S, Semigroup(MultiplicativeZero(S)));
true
gap> S := FullTransformationSemigroup(4);
<full transformation monoid of degree 4>
gap> T := Semigroup(Transformation([3, 4, 1, 2]),
>                   Transformation([1, 4, 2, 3]),
>                   Transformation([2, 1, 1, 3]));
<transformation semigroup of degree 4 with 3 generators>
gap> IsMaximalSubsemigroup(S, T);
true
gap> R := Semigroup(Transformation([3, 4, 1, 2]),
>                   Transformation([1, 4, 2, 2]),
>                   Transformation([2, 1, 1, 3]));
<transformation semigroup of degree 4 with 3 generators>
gap> IsMaximalSubsemigroup(S, R);
false]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>
