#############################################################################
##
#W  freeband.xml
#Y  Copyright (C) 2013-15                                   Julius Jonusas
##
##  Licensing information can be found in the README file of this package.
##
#############################################################################

<#GAPDoc Label="GreensDClassOfElement" >
<ManSection>
  <Oper Name = "GreensDClassOfElement" Arg = "S, x"
    Label="for a free band and element"/>
  <Returns>
    A Green's &D;-class
  </Returns>
  <Description>
    Let <A>S</A> be a free band. Two elements of <A> S </A> are &D;-related
    if and only if they have the same content i.e. the set of generators
    appearing in any factorization of the elements. Therefore, a &D;-class of
    a free band element <A> x </A> is the set of elements of <A> S </A> which
    have the same content as <A> x </A>.
<Example><![CDATA[
gap> S := FreeBand(3, "b");
<free band on the generators [ b1, b2, b3 ]>
gap> x := S.1 * S.2;
b1b2
gap> D := GreensDClassOfElement(S, x);
<Green's D-class: b1b2>
gap> IsGreensDClass(D);
true]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>


<#GAPDoc Label="FreeBand" >
<ManSection>
    <Func Name = "FreeBand" Arg = "rank[, name]" Label = "for a given rank"/>
    <Func Name = "FreeBand" Arg = "name1, name2, .. ." Label = "for a list of names"/>
    <Func Name = "FreeBand" Arg = "names" Label = "for various names"/>
    <Returns> A free band.</Returns>
    <Description>
     Returns a free band on <A>rank</A> generators, for a positive integer
     <A>rank</A>. If <A>rank</A> is not specified, the number of <A>names</A>
     is used. The resulting semigroup is always finite.
<Example><![CDATA[
gap> FreeBand(6);
<free band on the generators [ x1, x2, x3, x4, x5, x6 ]>
gap> FreeBand(6, "b");
<free band on the generators [ b1, b2, b3, b4, b5, b6 ]>
gap> FreeBand("a", "b", "c");
<free band on the generators [ a, b, c ]>
gap> FreeBand("a", "b", "c");
<free band on the generators [ a, b, c ]>
gap> S := FreeBand(["a", "b", "c"]);
<free band on the generators [ a, b, c ]>
gap> Size(S);
159
gap> gens := Generators(S);
[ a, b, c ]
gap> S.1 * S.2;
ab]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsFreeBandCategory" >
<ManSection>
    <Filt Name = "IsFreeBandCategory" Type = "Category"/>
    <Description>
      <C>IsFreeBandCategory</C> is the category of semigroups created using
      <Ref Func = "FreeBand" Label="for a given rank" />.
<Example><![CDATA[
gap> IsFreeBandCategory(FreeBand(3));
true
gap> IsFreeBand(SymmetricGroup(6));
false]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsFreeBand" >
<ManSection>
    <Prop Name = "IsFreeBand" Arg = "S" Label="for a given semigroup"/>
    <Returns><K>true</K> or <K>false</K>. </Returns>
    <Description>
      <C>IsFreeBand</C> returns <K>true</K> if the given semigroup <A>S</A> is a
      free band.
<Example><![CDATA[
gap> IsFreeBand(FreeBand(3));
true
gap> IsFreeBand(SymmetricGroup(6));
false
gap> IsFreeBand(FullTransformationMonoid(7));
false
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsFreeBandElement" >
<ManSection>
    <Filt Name = "IsFreeBandElement" Type = "Category"/>
    <Description>
    <C>IsFreeBandElement</C> is a <C>Category</C> containing the
    elements of a free band.
<Example><![CDATA[
gap> IsFreeBandElement(Generators(FreeBand(4))[1]);
true
gap> IsFreeBandElement(Transformation([1, 3, 4, 1]));
false
gap> IsFreeBandElement((1, 2, 3, 4));
false
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>


<#GAPDoc Label="IsFreeBandSubsemigroup" >
<ManSection>
    <Filt Name = "IsFreeBandSubsemigroup"/>
    <Description>
      <C>IsFreeBandSubsemigroup</C> is a synonym for <C>IsSemigroup</C> and
      <C>IsFreeBandElementCollection</C>.
<Example><![CDATA[
gap> S := FreeBand(2);
<free band on the generators [ x1, x2 ]>
gap> x := S.1;
x1
gap> y := S.2;
x2
gap> new := Semigroup([x * y, x]);
<semigroup with 2 generators>
gap> IsFreeBand(new);
false
gap> IsFreeBandSubsemigroup(new);
true]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="ContentOfFreeBandElement" >
<ManSection>
    <Attr Name = "ContentOfFreeBandElement" Arg = "x" /> 
    <Attr Name = "ContentOfFreeBandElementCollection" Arg = "coll" /> 
    <Returns> A list of integers </Returns>
    <Description>
      The content of a free band element <A>x</A> is the set of generators
      appearing in the word representing the element <A>x</A> of the free band.
      <P/>
      
      The function <C>ContentOfFreeBandElement</C> returns the content of free
      band element <A>x</A> represented as a list of integers, where <C>1</C>
      represents the first generator, <C>2</C> the second generator, and so on.
      <P/>

      The function <C>ContentOfFreeBandElementCollection</C> returns the
      the least list <C>C</C> for the collection of free band elements <A>coll</A>
      such that the content of every element in <A>coll</A>
      is contained in <C>C</C>.
<Example><![CDATA[
gap> S := FreeBand(2);
<free band on the generators [ x1, x2 ]>
gap> x := S.1;
x1
gap> y := S.2;
x2
gap> ContentOfFreeBandElement(x);
[ 1 ]
gap> ContentOfFreeBandElement(x * y);
[ 1, 2 ]
gap> ContentOfFreeBandElement(x * y * x);
[ 1, 2 ]
gap> ContentOfFreeBandElementCollection([x, y]);
[ 1, 2 ]]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsFreeBandElementCollection">
  <ManSection>
    <Filt Name="IsFreeBandElementCollection"  Type='Category'/>
    <Description>
      Every collection of elements of a free band belongs to the
      category <C>IsFreeBandElementCollection</C>. For example,
      every free band belongs to
      <C>IsFreeBandElementCollection</C>.
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="EqualInFreeBand">
  <ManSection>
    <Oper Name="EqualInFreeBand"  Arg="u, v"/>
    <Description>
      This operation takes a pair <A>u</A> and <A>v</A> of lists of
      positive integers or strings, representing words in a free semigroup.<P/>

      Where <C>F</C> is a free band over some alphabet containing the
      letters occurring in <A>u</A> and <A>v</A>, this operation returns <K>true</K>
      if <A>u</A> and <A>v</A> are equal in <C>F</C>, and <K>false</K>
      otherwise.<P/>

      Note that this operation is for lists and strings, as opposed to
      <C>FreeBandElement</C> objects.<P/>

      This is an implementation of an algorithm described by Jakub Radoszewski
      and Wojciech Rytter in <Cite Key="Radoszewski2010aa"/>.
      <Example><![CDATA[
gap> EqualInFreeBand("aa", "a");
true
gap> EqualInFreeBand("abcacba", "abcba");
true
gap> EqualInFreeBand("aab", "aac");
false
gap> EqualInFreeBand([1, 3, 3], [2]);
false
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>
