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

<#GAPDoc Label="RightBlocks">
  <ManSection>
    <Attr Name = "RightBlocks" Arg = "x"/>
    <Returns>The right blocks of a bipartition.</Returns>
    <Description>
      <C>RightBlocks</C> returns the right blocks of the bipartition <A>x</A>.
      <P/>

      The <E>right blocks</E> of a bipartition <A>x</A> are just the
      intersections of the blocks of <A>x</A> with <C>[-n .. -1]</C> where
      <C>n</C> is the degree of <A>x</A>, the values in transverse blocks are
      positive, and the values in non-transverse blocks are negative. <P/>

      The right blocks of a bipartition are &GAP; objects in their own right,
      and are not simply a list of blocks of <A>x</A>; see <Ref
        Sect="section-blocks"/> for more information. <P/>

      The significance of this notion lies in the fact that bipartitions
      <A>x</A> and <C>y</C> are &L;-related in the partition monoid if and only
      if they have equal right blocks.
      <Example><![CDATA[
gap> x := Bipartition([[1, 4, 7, 8, -4], [2, 3, 5, -2, -7],
>                      [6, -1], [-3], [-5, -6, -8]]);;
gap> RightBlocks(x);
<blocks: [ 1* ], [ 2*, 7* ], [ 3 ], [ 4* ], [ 5, 6, 8 ]>
gap> LeftBlocks(x);
<blocks: [ 1*, 4*, 7*, 8* ], [ 2*, 3*, 5* ], [ 6* ]>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="LeftBlocks">
  <ManSection>
    <Attr Name="LeftBlocks" Arg="x"/>
    <Returns>The left blocks of a bipartition.</Returns>
    <Description>
      <C>LeftBlocks</C> returns the left blocks of the
      bipartition <A>x</A>.
      <P/>

      The <E>left blocks</E> of a bipartition <A>x</A> are just the
      intersections of the blocks of <A>x</A> with <C>[1..n]</C> where <C>n</C>
      is the degree of <A>x</A>, the values in transverse blocks are positive,
      and the values in non-transverse blocks are negative.
      <P/>

      The left blocks of a bipartition are &GAP; objects in their own right,
      and are not simply a list of blocks of <A>x</A>; see <Ref
        Sect="section-blocks"/> for more information.
      <P/>

      The significance of this notion lies in the fact that bipartitions
      <A>x</A> and <C>y</C> are &R;-related in the partition monoid if and only
      if they have equal left blocks.
      <Example><![CDATA[
gap> x := Bipartition([[1, 4, 7, 8, -4], [2, 3, 5, -2, -7],
>                      [6, -1], [-3], [-5, -6, -8]]);;
gap> RightBlocks(x);
<blocks: [ 1* ], [ 2*, 7* ], [ 3 ], [ 4* ], [ 5, 6, 8 ]>
gap> LeftBlocks(x);
<blocks: [ 1*, 4*, 7*, 8* ], [ 2*, 3*, 5* ], [ 6* ]>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="NrBlocks">
  <ManSection>
    <Attr Name = "NrBlocks" Arg = "blocks" Label="for blocks"/>
    <Attr Name = "NrBlocks" Arg = "f" Label="for a bipartition"/>
    <Returns>A positive integer.</Returns>
    <Description>
      If <A>blocks</A> is some blocks or <A>f</A> is a bipartition, then
      <C>NrBlocks</C> returns the number of blocks in <A>blocks</A> or <A>f</A>,
      respectively.
      <Example><![CDATA[
gap> blocks := BLOCKS_NC([[-1, -2, -3, -4], [-5], [6]]);
<blocks: [ 1, 2, 3, 4 ], [ 5 ], [ 6* ]>
gap> NrBlocks(blocks);
3
gap> x := Bipartition([
>   [1, 5], [2, 4, -2, -4], [3, 6, -1, -5, -6], [-3]]);
<bipartition: [ 1, 5 ], [ 2, 4, -2, -4 ], [ 3, 6, -1, -5, -6 ], 
 [ -3 ]>
gap> NrBlocks(x);
4]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="NrLeftBlocks">
  <ManSection>
    <Attr Name = "NrLeftBlocks" Arg = "x"/>
    <Returns>A non-negative integer.</Returns>
    <Description>
      When the argument is a bipartition <A>x</A>, <C>NrLeftBlocks</C> returns
      the number of left blocks of <A>x</A>, i.e. the number of blocks of
      <A>x</A> intersecting <C>[1 .. n]</C> non-trivially.
      <Example><![CDATA[
gap> x := Bipartition([[1, 2, 3, 4, 5, 6, 8], [7, -2, -3],
>                      [-1, -4, -7, -8], [-5, -6]]);;
gap> NrLeftBlocks(x);
2
gap> LeftBlocks(x);
<blocks: [ 1, 2, 3, 4, 5, 6, 8 ], [ 7* ]>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="NrRightBlocks">
  <ManSection>
    <Attr Name = "NrRightBlocks" Arg = "x"/>
    <Returns>A non-negative integer.</Returns>
    <Description>
      When the argument is a bipartition <A>x</A>, <C>NrRightBlocks</C> returns
      the number of right blocks of <A>x</A>, i.e. the number of blocks of
      <A>x</A> intersecting <C>[-n .. -1]</C> non-trivially.
      <Example><![CDATA[
gap> x := Bipartition([[1, 2, 3, 4, 6, -2, -7], [5, -1, -3, -8],
>                      [7, -4, -6], [8], [-5]]);;
gap> RightBlocks(x);
<blocks: [ 1*, 3*, 8* ], [ 2*, 7* ], [ 4*, 6* ], [ 5 ]>
gap> NrRightBlocks(x);
4]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="DomainOfBipartition">
  <ManSection>
    <Attr Name = "DomainOfBipartition" Arg = "x"/>
    <Returns>A list of positive integers.</Returns>
    <Description>
      If <A>x</A> is a bipartition, then <C>DomainOfBipartition</C> returns the
      domain of <A>x</A>. The <E>domain</E> of <A>x</A> consists of those
      numbers <C>i</C> in <C>[1 .. n]</C> such that <C>i</C> is contained in a
      transverse block of <A>x</A>, where <C>n</C> is the degree of <A>x</A>
      (see <Ref Attr="DegreeOfBipartition"/>).
      <Example><![CDATA[
gap> x := Bipartition([[1, 2], [3, 4, 5, -5], [6, -6], 
>                      [-1, -2, -3], [-4]]);
<bipartition: [ 1, 2 ], [ 3, 4, 5, -5 ], [ 6, -6 ], [ -1, -2, -3 ], 
 [ -4 ]>
gap> DomainOfBipartition(x);
[ 3, 4, 5, 6 ]]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="CodomainOfBipartition">
  <ManSection>
    <Attr Name = "CodomainOfBipartition" Arg = "x"/>
    <Returns>A list of positive integers.</Returns>
    <Description>
      If <A>x</A> is a bipartition, then <C>CodomainOfBipartition</C> returns
      the codomain of <A>x</A>. The <E>codomain</E> of <A>x</A> consists of
      those numbers <C>i</C> in <C>[-n .. -1]</C> such that <C>i</C> is contained
      in a transverse block of <A>x</A>, where <C>n</C> is the degree of
      <A>x</A> (see <Ref Attr="DegreeOfBipartition"/>).
      <Example><![CDATA[
gap> x := Bipartition([[1, 2], [3, 4, 5, -5], [6, -6], 
>                      [-1, -2, -3], [-4]]);
<bipartition: [ 1, 2 ], [ 3, 4, 5, -5 ], [ 6, -6 ], [ -1, -2, -3 ], 
 [ -4 ]>
gap> CodomainOfBipartition(x);
[ -5, -6 ]]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IntRepOfBipartition">
  <ManSection>
    <Attr Name = "IntRepOfBipartition" Arg = "x"/>
    <Returns>A list of positive integers.</Returns>
    <Description>
      If <A>x</A> is a bipartition with degree <C>n</C>, then
      <C>IntRepOfBipartition</C> returns the <E>internal representation</E> of
      <A>x</A>: a list of length <C>2 * n</C> containing positive integers which
      correspond to the blocks of <A>x</A>. <P/>

      If <C>i</C> is in <C>[1 .. n]</C>, then <C>list[i]</C> refers to the point
      <C>i</C>; if <C>i</C> is in <C>[n + 1 .. 2 * n]</C>, then <C>list[i]</C>
      refers to the point <C>n - i</C> (a negative point).  Two points lie in
      the same block of the bipartition if and only if their entries in the list
      are equal. <P/>

      See also <Ref Oper="BipartitionByIntRep"/>.

      <Example><![CDATA[
gap> x := Bipartition([[1, -3], [3, 4], [2, -1, -2], [-4]]);
<bipartition: [ 1, -3 ], [ 2, -1, -2 ], [ 3, 4 ], [ -4 ]>
gap> IntRepOfBipartition(x);
[ 1, 2, 3, 3, 2, 2, 1, 4 ]
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="PartialPermLeqBipartition">
  <ManSection>
    <Oper Name = "PartialPermLeqBipartition" Arg = "x, y"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
      If <A>x</A> and <A>y</A> are partial perm bipartitions, i.e. they satisfy
      <Ref Prop = "IsPartialPermBipartition"/>, then this function returns
      <C>AsPartialPerm(<A>x</A>) &lt; AsPartialPerm(<A>y</A>)</C>.
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="NaturalLeqPartialPermBipartition">
  <ManSection>
    <Oper Name = "NaturalLeqPartialPermBipartition" Arg = "x, y"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
      The <E>natural partial order</E> <M>\leq</M> on an inverse semigroup
      <C>S</C> is defined by <C>s</C> <M>\leq</M> <C>t</C> if there exists an
      idempotent <C>e</C> in <C>S</C> such that <C>s = et</C>. Hence if <A>x</A>
      and <A>y</A> are partial perm bipartitions, then
      <A>x</A> <M>\leq</M> <A>y</A> if and only if <C>AsPartialPerm(<A>x</A>)</C>
      is a restriction of <C>AsPartialPerm(<A>y</A>)</C>.
      <P/>

      <C>NaturalLeqPartialPermBipartition</C> returns <K>true</K> if
      <C>AsPartialPerm(<A>x</A>)</C> is a restriction of
      <C>AsPartialPerm(<A>y</A>)</C> and <K>false</K> if it is not. Note that
      since this is a partial order and not a total order, it is possible that
      <A>x</A> and <A>y</A> are incomparable with respect to the natural
      partial order.
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="NaturalLeqBlockBijection">
  <ManSection>
    <Oper Name = "NaturalLeqBlockBijection" Arg = "x, y"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
      The <E>natural partial order</E> <M>\leq</M> on an inverse semigroup
      <C>S</C> is defined by <C>s</C> <M>\leq</M> <C>t</C> if there exists an
      idempotent <C>e</C> in <C>S</C> such that <C>s = et</C>. Hence if
      <A>x</A> and <A>y</A> are block bijections, then
      <A>x</A> <M>\leq</M> <A>y</A> if and only if <A>x</A> contains <A>y</A>.
      <P/>

      <C>NaturalLeqBlockBijection</C> returns <K>true</K> if <A>x</A> is
      contained in <A>y</A> and <K>false</K> if it is not. Note that since this
      is a partial order and not a total order, it is possible that <A>x</A>
      and <A>y</A> are incomparable with respect to the natural partial order.
      <Example><![CDATA[
gap> x := Bipartition([[1, 2, -3], [3, -1, -2], [4, -4],
>                      [5, -5], [6, -6], [7, -7],
>                      [8, -8], [9, -9], [10, -10]]);;
gap> y := Bipartition([[1, -2], [2, -1], [3, -3],
>                      [4, -4], [5, -5], [6, -6], [7, -7],
>                      [8, -8], [9, -9], [10, -10]]);;
gap> z := Bipartition([Union([1 .. 10], [-10 .. -1])]);;
gap> NaturalLeqBlockBijection(x, y);
false
gap> NaturalLeqBlockBijection(y, x);
false
gap> NaturalLeqBlockBijection(z, x);
true
gap> NaturalLeqBlockBijection(z, y);
true]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsDualTransBipartition">
  <ManSection>
    <Prop Name = "IsDualTransBipartition" Arg = "x"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
    If the star of the bipartition <A>x</A> defines a transformation, then
    <C>IsDualTransBipartition</C> returns <K>true</K>, and if not, then
    <K>false</K> is returned.<P/>

    A bipartition is the dual of a transformation if and only if its number of
    right blocks equals its number of transverse blocks and its number of left
    blocks equals its degree.

    <Example><![CDATA[
gap> x := Bipartition([[1, -8, -9], [2, -1, -4], [3],
>                      [4], [5, -10], [6, -2, -5], [7, -3],
>                      [8], [9, -6, -7], [10]]);;
gap> IsDualTransBipartition(x);
true
gap> x := Bipartition([[1, 4, -3, -6], [2, 5, -4, -5],
>                      [3, 6, -1], [-2]]);;
gap> IsTransBipartition(x);
false
gap> Number(PartitionMonoid(3), IsDualTransBipartition);
27]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsBlockBijection">
  <ManSection>
    <Prop Name = "IsBlockBijection" Arg = "x"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
      If the bipartition <A>x</A> induces a bijection from the quotient of
      <C>[1 .. n]</C> by the blocks of <A>f</A> to the quotient of
      <C>[-n .. -1]</C> by the blocks of <A>f</A>, then <C>IsBlockBijection</C>
      return <K>true</K>, and if not, then it returns <K>false</K>. <P/>

      A bipartition is a block bijection if and only if its number of blocks,
      left blocks and right blocks are equal.
      <Example><![CDATA[
gap> x := Bipartition([[1, 4, 5, -2], [2, 3, -1], [6, -5, -6],
>                      [-3, -4]]);;
gap> IsBlockBijection(x);
false
gap> x := Bipartition([[1, 2, -3], [3, -1, -2], [4, -4], [5, -5]]);;
gap> IsBlockBijection(x);
true]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsUniformBlockBijection">
  <ManSection>
    <Prop Name = "IsUniformBlockBijection" Arg = "x"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
      If the bipartition <A>x</A> is a block bijection where every block
      contains an equal number of positive and negative entries, then
      <C>IsUniformBlockBijection</C> returns <K>true</K>, and otherwise it
      returns <K>false</K>.

      <Example><![CDATA[
gap> x := Bipartition([[1, 2, -3, -4], [3, -5], [4, -6],
> [5, -7], [6, -8], [7, -9], [8, -1], [9, -2]]);;
gap> IsBlockBijection(x);
true
gap> x := Bipartition([[1, 2, -3], [3, -1, -2], [4, -4],
> [5, -5]]);;
gap> IsUniformBlockBijection(x);
false]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsBipartition">
  <ManSection>
    <Filt Name = "IsBipartition" Arg = "obj" Type = "Category"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
   Every bipartition in &GAP; belongs to the category
    <C>IsBipartition</C>. Basic operations for bipartitions are
    <Ref Attr = "RightBlocks"/>,
    <Ref Attr = "LeftBlocks"/>,
    <Ref Oper = "ExtRepOfObj" Label="for a bipartition"/>,
    <Ref Attr = "LeftProjection"/>,
    <Ref Attr = "RightProjection"/>,
    <Ref Oper = "StarOp" Label="for a bipartition"/>,
    <Ref Attr = "DegreeOfBipartition"/>,
    <Ref Attr = "RankOfBipartition"/>,
    multiplication of two bipartitions of equal degree is
    via <K>*</K>.
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsBipartitionCollection">
  <ManSection>
    <Filt Name = "IsBipartitionCollection" Arg = "obj" Type = "Category"/>
    <Filt Name = "IsBipartitionCollColl" Arg = "obj" Type = "Category"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
       Every collection of bipartitions belongs to the category
     <C>IsBipartitionCollection</C>. For example, bipartition semigroups
     belong to <C>IsBipartitionCollection</C>.<P/>

     Every collection of collections of bipartitions belongs to
     <C>IsBipartitionCollColl</C>. For example, a list of bipartition
     semigroups belongs to <C>IsBipartitionCollColl</C>.
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="AsTransformation">
  <ManSection>
    <Attr Name = "AsTransformation" Arg = "x" Label="for a bipartition"/>
    <Returns>A transformation.</Returns>
    <Description>
      When the argument <A>x</A> is a bipartition, that mathematically defines
      a transformation, this function returns that transformation. A
      bipartition <A>x</A> defines a transformation if and only if its right
      blocks are the image list of a permutation of <C>[1 .. n]</C> where
      <C>n</C> is the degree of <A>x</A>. <P/>

      See <Ref Prop="IsTransBipartition"/>.
      <Example><![CDATA[
gap> x := Bipartition([[1, -3], [2, -2], [3, 5, 10, -7],
>                      [4, -12], [6, 7, -6], [8, -5], [9, -11],
>                      [11, 12, -10], [-1], [-4], [-8], [-9]]);;
gap> AsTransformation(x);
Transformation( [ 3, 2, 7, 12, 7, 6, 6, 5, 11, 7, 10, 10 ] )
gap> IsTransBipartition(x);
true
gap> x := Bipartition([[1, 5], [2, 4, 8, 10],
>                      [3, 6, 7, -1, -2], [9, -4, -6, -9],
>                      [-3, -5], [-7, -8], [-10]]);;
gap> AsTransformation(x);
Error, the argument (a bipartition) does not define a transformation]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="AsPermutation">
  <ManSection>
    <Attr Name = "AsPermutation" Arg = "x" Label="for a bipartition"/>
    <Returns>A permutation.</Returns>
    <Description>
      When the argument <A>x</A> is a bipartition that mathematically defines a
      permutation, this function returns that permutation. <P/>

      A bipartition <A>x</A> defines a permutation if and only if its numbers of
      left, right, and transverse blocks all equal its degree.<P/>

      See <Ref Prop = "IsPermBipartition"/>.
      <Example><![CDATA[
gap> x := Bipartition([[1, -6], [2, -4], [3, -2], [4, -5],
>                      [5, -3], [6, -1]]);;
gap> IsPermBipartition(x);
true
gap> AsPermutation(x);
(1,6)(2,4,5,3)
gap> AsBipartition(last) = x;
true]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="AsPartialPerm">
  <ManSection>
    <Oper Name = "AsPartialPerm" Arg = "x" Label="for a bipartition"/>
    <Returns>A partial perm.</Returns>
    <Description>
      When the argument <A>x</A> is a bipartition that mathematically defines a
      partial perm, this function returns that partial perm.
      <P/>

      A bipartition <A>x</A> defines a partial perm if and only if its numbers
      of left and right blocks both equal its degree.
      <P/>

      See <Ref Prop = "IsPartialPermBipartition"/>.
      <Example><![CDATA[
gap> x := Bipartition([[1, -4], [2, -2], [3, -10], [4, -5],
>                      [5, -9], [6], [7], [8, -6], [9, -3], [10, -8],
>                      [-1], [-7]]);;
gap> IsPartialPermBipartition(x);
true
gap> AsPartialPerm(x);
[1,4,5,9,3,10,8,6](2)
gap> x := Bipartition([[1, -2, -4], [2, 3, 4, -3], [-1]]);;
gap> IsPartialPermBipartition(x);
false
gap> AsPartialPerm(x);
Error, the argument (a bipartition) does not define a partial perm]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="AsBlockBijection">
  <ManSection>
    <Oper Name = "AsBlockBijection" Arg = "x[, n]"/>
    <Returns>A block bijection.</Returns>
    <Description>
      When the argument <A>x</A> is a partial perm and <A>n</A> is a positive
      integer which is greater than the maximum of the degree and codegree of
      <A>x</A>, this function returns a block bijection corresponding to
      <A>x</A>. This block bijection has the same non-singleton classes as
      <C>g := AsBipartition(<A>x</A>, <A>n</A>)</C> and one additional class
      which is the union the singleton classes of <C>g</C>.
      <P/>

      If the optional second argument <A>n</A> is not present, then the maximum
      of the degree and codegree of <A>x</A> plus 1 is used by default. If the
      second argument <A>n</A> is not greater than this maximum, then an error
      is given.
      <P/>

      This is the value at <A>x</A> of the embedding of the symmetric inverse
      monoid into the dual symmetric inverse monoid given in the
      FitzGerald-Leech Theorem <Cite Key = "Fitzgerald1998aa"/>.
      <P/>

      When the argument <A>x</A> is a partial perm bipartition (see <Ref
        Prop="IsPartialPermBipartition" />) then this operation
      returns <C>AsBlockBijection(AsPartialPerm(<A>x</A>)[, <A>n</A>])</C>.

<Example><![CDATA[
gap> x := PartialPerm([1, 2, 3, 6, 7, 10], [9, 5, 6, 1, 7, 8]);
[2,5][3,6,1,9][10,8](7)
gap> AsBipartition(x, 11);
<bipartition: [ 1, -9 ], [ 2, -5 ], [ 3, -6 ], [ 4 ], [ 5 ], 
 [ 6, -1 ], [ 7, -7 ], [ 8 ], [ 9 ], [ 10, -8 ], [ 11 ], [ -2 ], 
 [ -3 ], [ -4 ], [ -10 ], [ -11 ]>
gap> AsBlockBijection(x, 10);
Error, the 2nd argument (a pos. int.) is less than or equal to the max\
imum of the degree and codegree of the 1st argument (a partial perm)
gap> AsBlockBijection(x, 11);
<block bijection: [ 1, -9 ], [ 2, -5 ], [ 3, -6 ], 
 [ 4, 5, 8, 9, 11, -2, -3, -4, -10, -11 ], [ 6, -1 ], [ 7, -7 ], 
 [ 10, -8 ]>
gap> x := Bipartition([[1, -3], [2], [3, -2], [-1]]);;
gap> IsPartialPermBipartition(x);
true
gap> AsBlockBijection(x);
<block bijection: [ 1, -3 ], [ 2, 4, -1, -4 ], [ 3, -2 ]>]]></Example>
  </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="AsBipartition">
  <ManSection>
    <Oper Name = "AsBipartition" Arg = "x[, n]"/>
    <Returns>A bipartition.</Returns>
  <Description>
  <C>AsBipartition</C> returns the bipartition, permutation, transformation, or
  partial permutation <A>x</A>, as a bipartition of degree <A>n</A>.<P/>

  There are several possible arguments for <C>AsBipartition</C>:
  <List>

    <Mark>permutations</Mark>
    <Item>
      If <A>x</A> is a permutation and <A>n</A> is a positive integer, then
      <C>AsBipartition(<A>x</A>, <A>n</A>)</C> returns the bipartition
      on <C>[1 .. <A>n</A>]</C> with classes <C>[i, i ^ <A>x</A>]</C>
      for all <C>i = 1 .. n</C>.<P/>

      If no positive integer <A>n</A> is specified, then
      the largest moved point of <A>x</A> is used as the value for <A>n</A>; see
      <Ref Attr = "LargestMovedPoint" Label="for a permutation" BookName =
        "ref"/>.
    </Item>

    <Mark>transformations</Mark>
    <Item>
      If <A>x</A> is a transformation and <A>n</A> is a positive integer
      such that <A>x</A> is a transformation of <C>[1 .. <A>n</A>]</C>, then
      <C>AsTransformation</C> returns the bipartition with classes
      <M>(i)f ^ {-1}\cup \{i\}</M> for all <C>i</C> in the image of <A>x</A>.<P/>

      If the positive integer <A>n</A> is not specified, then the
      degree of <A>x</A> is used as the value for <A>n</A>.
    </Item>

    <Mark>partial permutations</Mark>
    <Item>
      If <A>x</A> is a partial permutation and <A>n</A> is a positive integer,
      then <C>AsBipartition</C> returns the bipartition with classes <C>[i, i ^
        <A>x</A>]</C> for <C>i</C> in <C>[1 .. <A>n</A>]</C>.  Thus the degree
      of the returned bipartition is the maximum of <A>n</A> and the values
      <C>i ^ <A>x</A></C> where <C>i</C> in <C>[1 .. <A>n</A>]</C>.<P/>

      If the optional argument <A>n</A> is not present, then the default value
      of the maximum of the largest moved point and the largest image of a
      moved point of <A>x</A> plus <C>1</C> is used.
    </Item>

    <Mark>bipartitions</Mark>
    <Item>
      If <A>x</A> is a bipartition and <A>n</A> is a non-negative integer, then
      <C>AsBipartition</C> returns a bipartition corresponding to <A>x</A> with
      degree <A>n</A>. <P/>

      If <A>n</A> equals the degree of <A>x</A>, then <A>x</A>
      is returned. If <A>n</A> is less than the degree of <A>x</A>, then this
      function returns the bipartition obtained from <A>x</A> by removing the
      values exceeding <A>n</A> or less than <A>-n</A> from the blocks of <A>x</A>.
      If <A>n</A> is greater than the degree of <A>x</A>, then this function
      returns the bipartition with the same blocks as <A>x</A> and the singleton
      blocks <C>i</C> and <C>-i</C> for all <C>i</C> greater than the degree of
      <A>x</A>
    </Item>

    <Mark>pbrs</Mark>
    <Item>
      If <A>x</A> is a pbr satisfying <Ref Prop = "IsBipartitionPBR"/> and
      <A>n</A> is a non-negative integer, then <C>AsBipartition</C> returns the
      bipartition corresponding to <A>x</A> with degree <A>n</A>.
    </Item>

  </List>

  <Example><![CDATA[
gap> x := Transformation([3, 5, 3, 4, 1, 2]);;
gap> AsBipartition(x, 5);
<bipartition: [ 1, 3, -3 ], [ 2, -5 ], [ 4, -4 ], [ 5, -1 ], [ -2 ]>
gap> AsBipartition(x);
<bipartition: [ 1, 3, -3 ], [ 2, -5 ], [ 4, -4 ], [ 5, -1 ], 
 [ 6, -2 ], [ -6 ]>
gap> AsBipartition(x, 10);
<bipartition: [ 1, 3, -3 ], [ 2, -5 ], [ 4, -4 ], [ 5, -1 ], 
 [ 6, -2 ], [ 7, -7 ], [ 8, -8 ], [ 9, -9 ], [ 10, -10 ], [ -6 ]>
gap> AsBipartition((1, 3)(2, 4));
<block bijection: [ 1, -3 ], [ 2, -4 ], [ 3, -1 ], [ 4, -2 ]>
gap> AsBipartition((1, 3)(2, 4), 10);
<block bijection: [ 1, -3 ], [ 2, -4 ], [ 3, -1 ], [ 4, -2 ], 
 [ 5, -5 ], [ 6, -6 ], [ 7, -7 ], [ 8, -8 ], [ 9, -9 ], [ 10, -10 ]>
gap> x := PartialPerm([1, 2, 3, 4, 5, 6], [6, 7, 1, 4, 3, 2]);;
gap> AsBipartition(x, 11);
<bipartition: [ 1, -6 ], [ 2, -7 ], [ 3, -1 ], [ 4, -4 ], [ 5, -3 ], 
 [ 6, -2 ], [ 7 ], [ 8 ], [ 9 ], [ 10 ], [ 11 ], [ -5 ], [ -8 ], 
 [ -9 ], [ -10 ], [ -11 ]>
gap> AsBipartition(x);
<bipartition: [ 1, -6 ], [ 2, -7 ], [ 3, -1 ], [ 4, -4 ], [ 5, -3 ], 
 [ 6, -2 ], [ 7 ], [ -5 ]>
gap> AsBipartition(Transformation([1, 1, 2]), 1);
<block bijection: [ 1, -1 ]>
gap> x := Bipartition([[1, 2, -2], [3], [4, 5, 6, -1],
>                      [-3, -4, -5, -6]]);;
gap> AsBipartition(x, 0);
<empty bipartition>
gap> AsBipartition(x, 2);
<bipartition: [ 1, 2, -2 ], [ -1 ]>
gap> AsBipartition(x, 8);
<bipartition: [ 1, 2, -2 ], [ 3 ], [ 4, 5, 6, -1 ], [ 7 ], [ 8 ], 
 [ -3, -4, -5, -6 ], [ -7 ], [ -8 ]>
gap> x := PBR(
> [[-1, 1, 2, 3, 4], [-1, 1, 2, 3, 4],
>  [-1, 1, 2, 3, 4], [-1, 1, 2, 3, 4]],
> [[-1, 1, 2, 3, 4], [-2], [-3], [-4]]);;
gap> AsBipartition(x);
<bipartition: [ 1, 2, 3, 4, -1 ], [ -2 ], [ -3 ], [ -4 ]>
gap> AsBipartition(x, 2);
<bipartition: [ 1, 2, -1 ], [ -2 ]>
gap> AsBipartition(x, 4);
<bipartition: [ 1, 2, 3, 4, -1 ], [ -2 ], [ -3 ], [ -4 ]>
gap> AsBipartition(x, 5);
<bipartition: [ 1, 2, 3, 4, -1 ], [ 5 ], [ -2 ], [ -3 ], [ -4 ], 
 [ -5 ]>
gap> AsBipartition(x, 0);
<empty bipartition>]]></Example>
  </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsTransBipartition">
  <ManSection>
    <Prop Name="IsTransBipartition" Arg="x"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
    If the bipartition <A>x</A> defines a transformation, then
    <C>IsTransBipartition</C> returns <K>true</K>, and if not, then
    <K>false</K> is returned.<P/>

    A bipartition <A>x</A> defines a transformation if and only if the number of
    left blocks equals the number of transverse blocks and the number of right
    blocks equals the degree.

    <Example><![CDATA[
gap> x := Bipartition([[1, 4, -2], [2, 5, -6], [3, -7],
>                      [6, 7, -9], [8, 9, -1], [10, -5],
>                      [-3], [-4], [-8], [-10]]);;
gap> IsTransBipartition(x);
true
gap> x := Bipartition([[1, 4, -3, -6], [2, 5, -4, -5],
>                      [3, 6, -1], [-2]]);;
gap> IsTransBipartition(x);
false
gap> Number(PartitionMonoid(3), IsTransBipartition);
27]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsPermBipartition">
  <ManSection>
    <Prop Name = "IsPermBipartition" Arg = "x"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
    If the bipartition <A>x</A> defines a permutation, then
    <C>IsPermBipartition</C> returns <K>true</K>, and if not, then
    <K>false</K> is returned.<P/>

    A bipartition is a permutation if its numbers of left, right,
    and transverse blocks all equal its degree.

  <Example><![CDATA[
gap> x := Bipartition([
>   [1, 4, -1], [2, -3], [3, 6, -5], [5, -2, -4, -6]]);;
gap> IsPermBipartition(x);
false
gap> x := Bipartition([[1, -3], [2, -4], [3, -6], [4, -1],
>                      [5, -5], [6, -2], [7, -8], [8, -7]]);;
gap> IsPermBipartition(x);
true]]></Example>
  </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsPartialPermBipartition">
  <ManSection>
    <Prop Name = "IsPartialPermBipartition" Arg = "x"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
    If the bipartition <A>x</A> defines a partial permutation, then
    <C>IsPartialPermBipartition</C> returns <K>true</K>, and if not, then
    <K>false</K> is returned.<P/>

    A bipartition <A>x</A> defines a partial permutation if and only if the
    numbers of left and right blocks of <A>x</A> equal the degree of <A>x</A>.

  <Example><![CDATA[
gap> x := Bipartition([
>   [1, 4, -1], [2, -3], [3, 6, -5], [5, -2, -4, -6]]);;
gap> IsPartialPermBipartition(x);
false
gap> x := Bipartition([[1, -3], [2], [-4], [3, -6], [4, -1],
>                      [5, -5], [6, -2], [7, -8], [8, -7]]);;
gap> IsPermBipartition(x);
false
gap> IsPartialPermBipartition(x);
true]]></Example>
  </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="BipartitionByIntRep">
  <ManSection>
    <Oper Name = "BipartitionByIntRep" Arg = "list"/>
    <Returns>A bipartition.</Returns>
    <Description>
      It is possible to create a bipartition using its internal
      representation. The argument <A>list</A> must be a list of positive
      integers not greater than <C>n</C>, of length <C>2 * n</C>, and where
      <C>i</C> appears in the list only if <C>i-1</C> occurs earlier in the
      list. <P/>

      For example, the internal representation of the bipartition with blocks
      <Log>[1, -1], [2, 3, -2], [-3]</Log> has
      internal representation
      <Log>[1, 2, 2, 1, 2, 3]</Log>
      The internal representation indicates that the number <C>1</C> is in
      class <C>1</C>, the number <C>2</C> is in class <C>2</C>, the number
      <C>3</C> is in class <C>2</C>, the number <C>-1</C> is
      in class <C>1</C>, the number <C>-2</C> is in class <C>2</C>, and
      <C>-3</C> is in class <C>3</C>.
      As another example, <C>[1, 3, 2, 1]</C> is not the internal
      representation of any bipartition since there is no <C>2</C> before the
      <C>3</C> in the second position.<P/>

      In its first form <C>BipartitionByIntRep</C> verifies that the argument
      <A>list</A> is the internal representation of a bipartition. <P/>

      See also <Ref Oper="IntRepOfBipartition"/>.

      <Example><![CDATA[
gap> BipartitionByIntRep([1, 2, 2, 1, 3, 4]);
<bipartition: [ 1, -1 ], [ 2, 3 ], [ -2 ], [ -3 ]>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="PermLeftQuoBipartition">
  <ManSection>
    <Oper Name = "PermLeftQuoBipartition" Arg = "x, y"/>
    <Returns>A permutation.</Returns>
    <Description>
      If <A>x</A> and <A>y</A> are bipartitions with equal left and right
      blocks, then <C>PermLeftQuoBipartition</C> returns the permutation of the
      indices of the right blocks of <A>x</A> (and <A>y</A>) induced by
      <C>Star(<A>x</A>) * <A>y</A></C>. <P/>

      <C>PermLeftQuoBipartition</C> verifies that <A>x</A> and <A>y</A> have
      equal left and right blocks, and returns an error if they do not.

      <Example><![CDATA[
gap> x := Bipartition([[1, 4, 6, 7, 8, 10], [2, 5, -1, -2, -8],
>                      [3, -3, -6, -7, -9], [9, -4, -5], [-10]]);;
gap> y := Bipartition([[1, 4, 6, 7, 8, 10], [2, 5, -3, -6, -7, -9],
>                      [3, -4, -5], [9, -1, -2, -8], [-10]]);;
gap> PermLeftQuoBipartition(x, y);
(1,2,3)
gap> Star(x) * y;
<bipartition: [ 1, 2, 8, -3, -6, -7, -9 ], [ 3, 6, 7, 9, -4, -5 ], 
 [ 4, 5, -1, -2, -8 ], [ 10 ], [ -10 ]>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IdentityBipartition">
  <ManSection>
    <Oper Name="IdentityBipartition" Arg="n"/>
    <Returns>The identity bipartition.</Returns>
    <Description>
      Returns the identity bipartition with degree <A>n</A>.
      <Example><![CDATA[
gap> IdentityBipartition(10);
<block bijection: [ 1, -1 ], [ 2, -2 ], [ 3, -3 ], [ 4, -4 ], 
 [ 5, -5 ], [ 6, -6 ], [ 7, -7 ], [ 8, -8 ], [ 9, -9 ], [ 10, -10 ]>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="RankOfBipartition">
  <ManSection>
    <Attr Name = "RankOfBipartition" Arg = "x"/>
    <Attr Name = "NrTransverseBlocks" Arg = "x" Label="for a bipartition"/>
    <Returns>The rank of a bipartition.</Returns>
    <Description>
      When the argument is a bipartition <A>x</A>, <C>RankOfBipartition</C>
      returns the number of blocks of <A>x</A> containing both positive and
      negative entries, i.e. the number of transverse blocks of <A>x</A>.
      <P/>

      <C>NrTransverseBlocks</C> is just a synonym for <C>RankOfBipartition</C>.
      <Example><![CDATA[
gap> x := Bipartition([[1, 2, 6, 7, -4, -5, -7], [3, 4, 5, -1, -3],
>                      [8, -9], [9, -2], [-6], [-8]]);
<bipartition: [ 1, 2, 6, 7, -4, -5, -7 ], [ 3, 4, 5, -1, -3 ], 
 [ 8, -9 ], [ 9, -2 ], [ -6 ], [ -8 ]>
gap> RankOfBipartition(x);
4]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="DegreeOfBipartition">
  <ManSection>
    <Attr Name = "DegreeOfBipartition" Arg = "x"/>
    <Attr Name = "DegreeOfBipartitionCollection" Arg = "x"/>
    <Returns>A positive integer.</Returns>
    <Description>
      The degree of a bipartition is, roughly speaking, the number of points
      where it is defined. More precisely, if <A>x</A> is a bipartition defined
      on <C>2 * n</C> points, then the degree of <A>x</A> is <C>n</C>. <P/>

      The degree of a collection <A>coll</A> of bipartitions of equal degree is
      just the degree of any (and every) bipartition in <A>coll</A>. The degree
      of collection of bipartitions of unequal degrees is not defined.

<Example><![CDATA[
gap> x := Bipartition([[1, 7, -3, -8], [2, 6],
>                      [3], [4, -7, -9], [5, 9, -2],
>                      [8, -1, -4, -6], [-5]]);;
gap> DegreeOfBipartition(x);
9
gap> S := BrauerMonoid(5);
<regular bipartition *-monoid of degree 5 with 3 generators>
gap> IsBipartitionCollection(S);
true
gap> DegreeOfBipartitionCollection(S);
5]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="Bipartition">
  <ManSection>
    <Func Name = "Bipartition" Arg = "blocks"/>
    <Returns>A bipartition.</Returns>
    <Description>
      <C>Bipartition</C> returns the bipartition <C>x</C> with equivalence
      classes <A>blocks</A>, which should be a list of duplicate-free lists
      whose union is <C>[-n .. -1]</C> union <C>[1 .. n]</C> for some positive
      integer <C>n</C>.
      <P/>

      <C>Bipartition</C> returns an error if the argument does not define a
      bipartition.
      <Example><![CDATA[
gap> x := Bipartition([[1, -1], [2, 3, -3], [-2]]);
<bipartition: [ 1, -1 ], [ 2, 3, -3 ], [ -2 ]>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="ExtRepOfObjBipart">
  <ManSection>
    <Oper Name = "ExtRepOfObj" Arg = "x" Label = "for a bipartition"/>
    <Returns>A partition of <C>[1 .. 2 * n]</C>.</Returns>
    <Description>
      If <C>n</C> is the degree of the bipartition
      <A>x</A>, then <C>ExtRepOfObj</C> returns the partition of
      <C>[-n .. -1]</C> union <C>[1 .. n]</C> corresponding to <A>x</A> as a
      sorted list of duplicate-free lists.
<Example><![CDATA[
gap> x := Bipartition([[1, 5, -3], [2, 4, -2, -4], [3, -1, -5]]);
<block bijection: [ 1, 5, -3 ], [ 2, 4, -2, -4 ], [ 3, -1, -5 ]>
gap> ExtRepOfObj(x);
[ [ 1, 5, -3 ], [ 2, 4, -2, -4 ], [ 3, -1, -5 ] ]]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="LeftProjection">
  <ManSection>
    <Attr Name = "LeftOne" Arg = "x" Label="for a bipartition"/>
    <Attr Name = "LeftProjection" Arg = "x"/>
    <Returns>A bipartition.</Returns>
    <Description>
      The <C>LeftProjection</C> of a bipartition <A>x</A> is the bipartition
      <C><A>x</A> * Star(<A>x</A>)</C>. It is so-named, since the left and
      right blocks of the left projection equal the left blocks of <A>x</A>.
      <P/>

      The left projection <C>e</C> of <A>x</A> is also a bipartition with the
      property that <C>e * <A>x</A> = <A>x</A></C>. <C>LeftOne</C> and
      <C>LeftProjection</C> are synonymous.
      <Example><![CDATA[
gap> x := Bipartition([
>   [1, 4, -1, -2, -6], [2, 3, 5, -4], [6, -3], [-5]]);;
gap> LeftOne(x);
<block bijection: [ 1, 4, -1, -4 ], [ 2, 3, 5, -2, -3, -5 ], 
 [ 6, -6 ]>
gap> LeftBlocks(x);
<blocks: [ 1*, 4* ], [ 2*, 3*, 5* ], [ 6* ]>
gap> RightBlocks(LeftOne(x));
<blocks: [ 1*, 4* ], [ 2*, 3*, 5* ], [ 6* ]>
gap> LeftBlocks(LeftOne(x));
<blocks: [ 1*, 4* ], [ 2*, 3*, 5* ], [ 6* ]>
gap> LeftOne(x) * x = x;
true]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="RightProjection">
  <ManSection>
    <Attr Name = "RightOne" Arg = "x" Label="for a bipartition"/>
    <Attr Name = "RightProjection" Arg = "x"/>
    <Returns>A bipartition.</Returns>
    <Description>
      The <C>RightProjection</C> of a bipartition <A>x</A> is the bipartition
      <C>Star(<A>x</A>) * <A>x</A></C>. It is so-named, since the left and
      right blocks of the right projection equal the right blocks of <A>x</A>.
      <P/>

      The right projection <C>e</C> of <A>x</A> is also a bipartition with the
      property that <C><A>x</A> * e = <A>x</A></C>. <C>RightOne</C> and
      <C>RightProjection</C> are synonymous.
      <Example><![CDATA[
gap> x := Bipartition([[1, -1, -4], [2, -2, -3], [3, 4], [5, -5]]);;
gap> RightOne(x);
<block bijection: [ 1, 4, -1, -4 ], [ 2, 3, -2, -3 ], [ 5, -5 ]>
gap> RightBlocks(RightOne(x));
<blocks: [ 1*, 4* ], [ 2*, 3* ], [ 5* ]>
gap> LeftBlocks(RightOne(x));
<blocks: [ 1*, 4* ], [ 2*, 3* ], [ 5* ]>
gap> RightBlocks(x);
<blocks: [ 1*, 4* ], [ 2*, 3* ], [ 5* ]>
gap> x * RightOne(x) = x;
true]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="StarOp">
  <ManSection>
    <Oper Name = "StarOp" Arg = "x" Label="for a bipartition"/>
    <Attr Name = "Star" Arg = "x" Label="for a bipartition"/>
    <Returns>A bipartition.</Returns>
    <Description>
      <C>StarOp</C> returns the unique bipartition <C>g</C> with the
      property that: <C><A>x</A> * g * <A>x</A> = <A>x</A></C>,
      <C>RightBlocks(<A>x</A>) = LeftBlocks(g)</C>, and
      <C>LeftBlocks(<A>x</A>) = RightBlocks(g)</C>. The star <C>g</C> can
      be obtained from <A>x</A> by changing the sign of every integer in the
      external representation of <A>x</A>.
      <Example><![CDATA[
gap> x := Bipartition([[1, -4], [2, 3, 4], [5], [-1], [-2, -3], [-5]]);
<bipartition: [ 1, -4 ], [ 2, 3, 4 ], [ 5 ], [ -1 ], [ -2, -3 ], 
 [ -5 ]>
gap> y := Star(x);
<bipartition: [ 1 ], [ 2, 3 ], [ 4, -1 ], [ 5 ], [ -2, -3, -4 ], 
 [ -5 ]>
gap> x * y * x = x;
true
gap> LeftBlocks(x) = RightBlocks(y);
true
gap> RightBlocks(x) = LeftBlocks(y);
true]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="RandomBipartition">
  <ManSection>
    <Oper Name = "RandomBipartition" Arg = "[rs, ]n"/>
    <Oper Name = "RandomBlockBijection" Arg = "[rs, ]n"/>
    <Returns>A bipartition.</Returns>
    <Description>
      If <A>n</A> is a positive integer, then <C>RandomBipartition</C> returns
      a random bipartition of degree <A>n</A>, and <C>RandomBlockBijection</C>
      returns a random block bijection of degree <A>n</A>. <P/>

      If the optional first argument <A>rs</A> is a random source, then this is
      used to generate the bipartition returned by <C>RandomBipartition</C> and
      <C>RandomBlockBijection</C>. <P/>

      Note that neither of these functions has a uniform distribution.
      <Log><![CDATA[
gap> x := RandomBipartition(6);
<bipartition: [ 1, 2, 3, 4 ], [ 5 ], [ 6, -2, -3, -4 ], [ -1, -5 ], [ -6 ]>
gap> x := RandomBlockBijection(4);
<block bijection: [ 1, 4, -2 ], [ 2, -4 ], [ 3, -1, -3 ]>]]></Log>
    </Description>
  </ManSection>
<#/GAPDoc>
