#############################################################################
##
#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);
<non-regular bipartition semigroup ideal of degree 4 with 3 generators
 >
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);
<regular bipartition semigroup ideal of degree 4 with 1 generator>
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>SemigroupByGenerators</C>. This function returns the semigroup 
      containing <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>). 

      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 := DClassNC(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([ (3,4), (2,8,7,4,3) ])>
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>

