#############################################################################
##
#W  ideals.xml
#Y  Copyright (C) 2014                                   James D. Mitchell
##
##  Licensing information can be found in the README file of this package.
##
#############################################################################
##
<#GAPDoc Label="MinimalIdealGeneratingSet">
  <ManSection>
    <Attr Name = "MinimalIdealGeneratingSet" Arg = "I"/>
    <Returns>A minimal set ideal generators of an ideal.</Returns>
    <Description>
      This function returns a minimal set of elements of the parent of the
      semigroup ideal <A>I</A> required to generate <A>I</A> as an ideal. <P/>

      The notion of the generators of an ideal is distinct from the notion of
      the generators of a semigroup or monoid.  In particular, the semigroup
      generated by the generators of an ideal is not, in general, equal to that
      ideal. Use <Ref Attr = "GeneratorsOfSemigroup" BookName = "ref"/> to obtain a
      semigroup generating set for an ideal, but beware that this can be very
      costly.

      <Example><![CDATA[
gap> S := Monoid([
> Bipartition([[1, 2, 3, -2], [4], [-1, -4], [-3]]),
> Bipartition([[1, 4, -2, -4], [2, -1, -3], [3]])]);;
gap> I := SemigroupIdeal(S, S);;
gap> MinimalIdealGeneratingSet(I);
[ <block bijection: [ 1, -1 ], [ 2, -2 ], [ 3, -3 ], [ 4, -4 ]> ]]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="GeneratorsOfSemigroupIdeal">
  <ManSection>
    <Attr Name = "GeneratorsOfSemigroupIdeal" Arg = "I"/>
    <Returns>The generators of an ideal of a semigroup.</Returns>
    <Description>
      This function returns the generators of the two-sided ideal <A>I</A>,
      which were used to defined <A>I</A> when it was created. <P/>

      If <A>I</A> is an ideal of a semigroup, then <A>I</A> is defined to be the
      least 2-sided ideal of a semigroup <C>S</C> containing a set <C>J</C> of
      elements of <C>S</C>. The set <C>J</C> is said to <E>generate</E> <A>I</A>.
      <P/>

      The notion of the generators of an ideal is distinct from the notion of
      the generators of a semigroup or monoid.  In particular, the semigroup
      generated by the generators of an ideal is not, in general, equal to that
      ideal. Use <Ref Attr = "GeneratorsOfSemigroup" BookName = "ref"/> to obtain a
      semigroup generating set for an ideal, but beware that this can be very
      costly.

      <Example><![CDATA[
gap> S := Semigroup(
> Bipartition([[1, 2, 3, 4, -1], [-2, -4], [-3]]),
> Bipartition([[1, 2, 3, -3], [4], [-1], [-2, -4]]),
> Bipartition([[1, 3, -2], [2, 4], [-1, -3, -4]]),
> Bipartition([[1], [2, 3, 4], [-1, -3, -4], [-2]]),
> Bipartition([[1], [2, 4, -2], [3, -4], [-1], [-3]]));;
gap> I := SemigroupIdeal(S, S.1 * S.2 * S.5);;
gap> GeneratorsOfSemigroupIdeal(I);
[ <bipartition: [ 1, 2, 3, 4, -4 ], [ -1 ], [ -2 ], [ -3 ]> ]
gap> I = Semigroup(GeneratorsOfSemigroupIdeal(I));
false]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="SemigroupIdeal">
  <ManSection>
    <Func Name = "SemigroupIdeal" Arg = "S, obj1, obj2, .. . "/>
    <Returns>
      An ideal of a semigroup.
    </Returns>
    <Description>
      If <A>obj1</A>, <A>obj2</A>, .. . are (any combination) of elements of the
      semigroup <A>S</A> or collections of elements of <A>S</A> (including
      subsemigroups and ideals of <A>S</A>),  then <C>SemigroupIdeal</C> returns the
      2-sided ideal of the semigroup <A>S</A> generated by the union of
      <A>obj1</A>,  <A>obj2</A>, .. .. <P/>

      The <Ref Func = "Parent" BookName = "ref"/> of the ideal returned by this
      function is <A>S</A>.

      <Example><![CDATA[
gap> S := SymmetricInverseMonoid(10);
<symmetric inverse monoid of degree 10>
gap> I := SemigroupIdeal(S, PartialPerm([1, 2]));
<inverse partial perm semigroup ideal of rank 10 with 1 generator>
gap> Size(I);
4151
gap> I := SemigroupIdeal(S, I, Idempotents(S));
<inverse partial perm semigroup ideal of rank 10 with 1025 generators>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="SupersemigroupOfIdeal">
  <ManSection>
    <Attr Name = "SupersemigroupOfIdeal" Arg = "I"/>
    <Returns>
      An ideal of a semigroup.
    </Returns>
    <Description>
      The <Ref Func = "Parent" BookName = "ref"/> of an ideal is the semigroup in
      which the ideal was created, i.e.  the first argument of <Ref
        Func = "SemigroupIdeal"/> or <C>SemigroupIdealByGenerators</C>. This
      function returns the semigroup containing the generators of the semigroup
      (i.e. <Ref Attr = "GeneratorsOfSemigroup" BookName = "ref"/>) which are
      used to compute the ideal.
      <P/>

      For a regular semigroup ideal, <C>SupersemigroupOfIdeal</C> will always be
      the top most semigroup used to create any of the predecessors of the
      current ideal. For example, if <C>S</C> is a semigroup, <C>I</C> is a
      regular ideal of <C>S</C>, and <C>J</C> is an ideal of <C>I</C>, then
      <C>Parent(J)</C> is <C>I</C> and <C>SupersemigroupOfIdeal(J)</C> is
      <C>S</C>.  This is to avoid computing a generating set for <C>I</C>,
      in this example, which is expensive and unnecessary since <C>I</C> is
      regular (in which case the Green's relations of <C>I</C> are just
      restrictions of the Green's relations on <C>S</C>).
      <P/>

      If <C>S</C> is a semigroup, <C>I</C> is a non-regular ideal of <C>S</C>,
      <C>J</C> is an ideal of <C>I</C>, then <C>SupersemigroupOfIdeal(J)</C> is
      <C>I</C>, since we currently have to use <C>GeneratorsOfSemigroup(I)</C>
      to compute anything about <C>I</C> other than its size and membership.

      <Example><![CDATA[
gap> S := FullTransformationSemigroup(8);
<full transformation monoid of degree 8>
gap> x := Transformation([2, 6, 7, 2, 6, 1, 1, 5]);;
gap> D := DClass(S, x);
<Green's D-class: Transformation( [ 2, 6, 7, 2, 6, 1, 1, 5 ] )>
gap> R := PrincipalFactor(D);
<Rees 0-matrix semigroup 1050x56 over Group([ (2,8,7,4,3), (3,4) ])>
gap> S := Semigroup(List([1 .. 10], x -> Random(R)));
<subsemigroup of 1050x56 Rees 0-matrix semigroup with 10 generators>
gap> I := SemigroupIdeal(S, MultiplicativeZero(S));
<regular Rees 0-matrix semigroup ideal with 1 generator>
gap> SupersemigroupOfIdeal(I);
<subsemigroup of 1050x56 Rees 0-matrix semigroup with 10 generators>
gap> J := SemigroupIdeal(I, Representative(MinimalDClass(S)));
<regular Rees 0-matrix semigroup ideal with 1 generator>
gap> Parent(J) = I;
true
gap> SupersemigroupOfIdeal(J) = I;
false]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="Ideals">
  <ManSection>
    <Attr Name = "Ideals" Arg = "S" Label = "for a semigroup"/>
    <Returns>
      An list of ideals.
    </Returns>
    <Description>
      If <A>S</A> is a finite non-empty semigroup, then this attribute returns a
      list of the non-empty two-sided ideals of <A>S</A>. <P/>

      The ideals are returned in no particular order, and each ideal uses the
      minimum possible number of generators
      (see <Ref Attr = "GeneratorsOfSemigroupIdeal"/>).

      <Example><![CDATA[
gap> S := Semigroup([Transformation([4, 3, 4, 1]),
>                    Transformation([4, 3, 2, 2])]);
<transformation semigroup of degree 4 with 2 generators>
gap> Ideals(S);
[ <non-regular transformation semigroup ideal of degree 4 with
      1 generator>, 
 <non-regular transformation semigroup ideal of degree 4 with
     1 generator>, 
<non-regular transformation semigroup ideal of degree 4 with
    2 generators>, 
<regular transformation semigroup ideal of degree 4 with 1 generator>,
<non-regular transformation semigroup ideal of degree 4 with
  1 generator>, 
<regular transformation semigroup ideal of degree 4 with 1 generator> 
]
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>
