#############################################################################
##
#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="f"/>
    <Returns>The right blocks of a bipartition.</Returns>
    <Description>
      <C>RightBlocks</C> returns the right blocks of the
      bipartition <A>f</A>.  <P/>
      
      The <E>right blocks</E> of a bipartition <A>f</A> are just the
      intersections of the blocks of <A>f</A> with <C>[-n..-1]</C> where
      <C>n</C> is the degree of <A>f</A>, the values in transverse blocks are
      positive, and the values in non-transverse blocks are negative. <P/>

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

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

<#GAPDoc Label="LeftBlocks">
  <ManSection>
    <Attr Name="LeftBlocks" Arg="f"/>
    <Returns>The left blocks of a bipartition.</Returns>
    <Description>
      <C>LeftBlocks</C> returns the left blocks of the
      bipartition <A>f</A>.  <P/>
      
      The <E>left blocks</E> of a bipartition <A>f</A> are just the
      intersections of the blocks of <A>f</A> with <C>[1..n]</C> where <C>n</C>
      is the degree of <A>f</A>, the values in transverse blocks are positive,
      and the values in non-transverse blocks are negative. <P/>
      
      The left blocks of bipartition are &GAP; objects in their own right, and
      are not simply a list of blocks of <A>f</A>; see <Ref
        Sect="section-blocks"/> for more information. <P/>
      
      The significance of this notion lies in the fact that bipartitions
      <C>x</C> and <C>y</C> are &R;-related in the partition monoid if and only
      if they have equal left blocks. 
      <Example><![CDATA[
gap> f:=Bipartition( [ [ 1, 4, 7, 8, -4 ], [ 2, 3, 5, -2, -7 ], 
> [ 6, -1 ], [ -3 ], [ -5, -6, -8 ] ] );;
gap> RightBlocks(f);
<blocks: [ 1 ], [ 2, 7 ], [ -3 ], [ 4 ], [ -5, -6, -8 ]>
gap> LeftBlocks(f);
<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:=BlocksNC([[ -1, -2, -3, -4 ], [ -5 ], [ 6 ]]);
<blocks: [ -1, -2, -3, -4 ], [ -5 ], [ 6 ]>
gap> NrBlocks(blocks);
3
gap> f:=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(f);
4]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

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

<#GAPDoc Label="NrRightBlocks">
  <ManSection>
    <Attr Name="NrRightBlocks" Arg="f"/>
    <Returns>A non-negative integer.</Returns>
    <Description>
      When the argument is a bipartition <A>f</A>, <C>NrRightBlocks</C> returns
      the number of right blocks of <A>f</A>, i.e. the number of blocks of
      <A>f</A> intersecting <C>[-n..-1]</C> non-trivially. 
      <Example><![CDATA[
gap> f:=Bipartition( [ [ 1, 2, 3, 4, 6, -2, -7 ], [ 5, -1, -3, -8 ], 
> [ 7, -4, -6 ], [ 8 ], [ -5 ] ] );;
gap> RightBlocks(f);
<blocks: [ 1, 3, 8 ], [ 2, 7 ], [ 4, 6 ], [ -5 ]>
gap> NrRightBlocks(f);
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="f"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
    If the star of the bipartition <A>f</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> f:=Bipartition( [ [ 1, -8, -9 ], [ 2, -1, -4 ], [ 3 ], [ 4 ], 
> [ 5, -10 ], [ 6, -2, -5 ], [ 7, -3 ], [ 8 ], [ 9, -6, -7 ], [ 10 ] ] );;
gap> IsDualTransBipartition(f);
true
gap> f:=Bipartition( [ [ 1, 4, -3, -6 ], [ 2, 5, -4, -5 ], [ 3, 6, -1 ], 
> [ -2 ] ] );;
gap> IsTransBipartition(f);
false
gap> Number(PartitionMonoid(3), IsDualTransBipartition);
27]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsBlockBijection">
  <ManSection>
    <Prop Name="IsBlockBijection" Arg="f"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
      If the bipartition <A>f</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> f:=Bipartition( [ [ 1, 4, 5, -2 ], [ 2, 3, -1 ], 
> [ 6, -5, -6 ], [ -3, -4 ] ] );;
gap> IsBlockBijection(f);
false
gap> f:=Bipartition( [ [ 1, 2, -3 ], [ 3, -1, -2 ], [ 4, -4 ], 
> [ 5, -5 ] ] );;
gap> IsBlockBijection(f);
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="BipartitionFamily">
  <ManSection>
    <Fam Name="BipartitionFamily"/>
    <Description>
      The family of all bipartitions is <C>BipartitionFamily</C>.
    </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 Attr="ExtRepOfBipartition"/>,
    <Ref Attr="LeftProjection"/>,
    <Ref Attr="RightProjection"/>,
    <Ref Oper="StarOp"/>, 
    <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"/>
    <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>. 
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="AsTransformation">
  <ManSection>
    <Oper Name="AsTransformation" Arg="f" Label="for a bipartition"/>
    <Returns>A transformation or <K>fail</K>.</Returns>
    <Description>
      When the argument <A>f</A> is a bipartition, that mathematically defines
      a transformation, this function returns that transformation. A
      bipartition <A>f</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>f</A>. <P/>
      
      See <Ref Oper="IsTransBipartition"/>. 
      <Example><![CDATA[
gap> f:=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(f);
Transformation( [ 3, 2, 7, 12, 7, 6, 6, 5, 11, 7, 10, 10 ] )
gap> IsTransBipartition(f);
true
gap> f:=Bipartition([[ 1, 5 ], [ 2, 4, 8, 10 ], [ 3, 6, 7, -1, -2 ], 
> [ 9, -4, -6, -9 ], [ -3, -5 ], [ -7, -8 ], [ -10 ]]);;
gap> AsTransformation(f);
fail]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="AsPermutation">
  <ManSection>
    <Oper Name="AsPermutation" Arg="f" Label="for a bipartition"/>
    <Returns>A permutation or <K>fail</K>.</Returns>
    <Description>
      When the argument <A>f</A> is a bipartition that mathematically defines a
      permutation, this function returns that permutation. <P/>
      
      A bipartition <A>f</A> defines a permutation if and only if its numbers of
      left, right, and transverse blocks all equal its degree.<P/>

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

<#GAPDoc Label="AsPartialPerm">
  <ManSection>
    <Oper Name="AsPartialPerm" Arg="f" Label="for a bipartition"/>
    <Returns>A partial perm or <K>fail</K>.</Returns>
    <Description>
      When the argument <A>f</A> is a bipartition that mathematically defines a
      partial perm, this function returns that partial perm. <P/>
      
      A bipartition <A>f</A> defines a partial perm if and only if its numbers of
      left and right blocks both equal its degree.<P/>

      See <Ref Oper="IsPartialPermBipartition"/>. 
      <Example><![CDATA[
gap> f:=Bipartition( [ [ 1, -4 ], [ 2, -2 ], [ 3, -10 ], [ 4, -5 ], 
> [ 5, -9 ], [ 6 ], [ 7 ], [ 8, -6 ], [ 9, -3 ], [ 10, -8 ], 
> [ -1 ], [ -7 ] ] );;
gap> IsPartialPermBipartition(f);
true
gap> AsPartialPerm(f);
[1,4,5,9,3,10,8,6](2)
gap> f:=Bipartition([[ 1, -2, -4 ], [ 2, 3, 4, -3 ], [ -1 ]]);;
gap> IsPartialPermBipartition(f);
false
gap> AsPartialPerm(f);
fail]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="AsBlockBijection">
  <ManSection>
    <Oper Name="AsBlockBijection" Arg="f[, n]"/>
    <Returns>A block bijection or <K>fail</K>.</Returns>
    <Description>
      When the argument <A>f</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>f</A>, this function returns a block bijection corresponding to
      <A>f</A>. This block bijection has the same non-singleton classes as
      <C>g:=AsBipartition(<A>f</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>f</A> plus 1 is used by default. If the
      second argument <A>n</A> is not greater than this maximum, then
      <K>fail</K> is returned.  <P/>

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

<Example><![CDATA[
gap> f:=PartialPerm( [ 1, 2, 3, 6, 7, 10 ], [ 9, 5, 6, 1, 7, 8 ] ) ;  
[2,5][3,6,1,9][10,8](7)
gap> AsBipartition(f, 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(f, 10);
fail
gap> AsBlockBijection(f, 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 ]>]]></Example>
  </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="AsBipartition">
  <ManSection>
    <Oper Name="AsBipartition" Arg="f[, n]"/>
    <Returns>A bipartition.</Returns>
  <Description>
  <C>AsBipartition</C> 
  returns the bipartition, permutation, transformation, or partial permutation
  <A>f</A>, as a bipartition of degree <A>n</A>.
  
  There are several possible arguments for <C>AsBipartition</C>:
  <List>
    <Mark>permutations</Mark>
    <Item>
      If <A>f</A> is a permutation and <A>n</A> is a positive integer, then 
      <C>AsBipartition(<A>f</A>, <A>n</A>)</C> returns the bipartition
      on <C>[1..<A>n</A>]</C> with classes <C>[i, i^<A>f</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>f</A> is used as the value for <A>n</A>; see
      <Ref Func="LargestMovedPoint" Label="for a permutation" BookName="ref"/>.
    </Item>
    <Mark>transformations</Mark>      
    <Item>
      If <A>f</A> is a transformation and <A>n</A> is a positive integer
      such that <A>f</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>f</A>.<P/>
      
      If the positive integer <A>n</A> is not specified, then the
      internal degree of <A>f</A> is used as the value for <A>n</A>.
    </Item> 
    <Mark>partial permutations</Mark>
    <Item>
      If <A>f</A> is a partial permutation <A>f</A> and <A>n</A> is a
      positive integer, then <C>AsBipartition</C> returns the bipartition 
      with classes <C>[i, i^<A>f</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>f</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>f</A> plus <C>1</C> is used.
    </Item>
    <Mark>bipartitions</Mark>
    <Item>
      If <A>f</A> is a bipartition and <A>n</A> is a non-negative integer, then 
      <C>AsBipartition</C> returns a bipartition corresponding to <A>f</A> with
      degree <A>n</A>. <P/>
      
      If <A>n</A> equals the degree of <A>f</A>, then <A>f</A>
      is returned. If <A>n</A> is less than the degree of <A>f</A>, then this
      function returns the bipartition obtained from <A>f</A> by removing the
      values exceeding <A>n</A> or less than <A>-n</A> from the blocks of <A>f</A>.
      If <A>n</A> is greater than the degree of <A>f</A>, then this function
      returns the bipartition with the same blocks as <A>f</A> and the singleton
      blocks <C>i</C> and <C>-i</C> for all <C>i</C> greater than the degree of
      <A>f</A>
    </Item>
  </List>

  <Example><![CDATA[
gap> f:=Transformation( [ 3, 5, 3, 4, 1, 2 ] );;
gap> AsBipartition(f, 5);
<bipartition: [ 1, 3, -3 ], [ 2, -5 ], [ 4, -4 ], [ 5, -1 ], [ -2 ]>
gap> AsBipartition(f);  
<bipartition: [ 1, 3, -3 ], [ 2, -5 ], [ 4, -4 ], [ 5, -1 ], 
 [ 6, -2 ], [ -6 ]>
gap> AsBipartition(f, 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> f:=PartialPerm( [ 1, 2, 3, 4, 5, 6 ], [ 6, 7, 1, 4, 3, 2 ] );;
gap> AsBipartition(f, 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(f);
<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> f:=Bipartition( [ [ 1, 2, -2 ], [ 3 ], [ 4, 5, 6, -1 ], 
> [ -3, -4, -5, -6 ] ] );;
gap> AsBipartition(f, 0);
<empty bipartition>
gap> AsBipartition(f, 2);
<bipartition: [ 1, 2, -2 ], [ -1 ]>
gap> AsBipartition(f, 8);
<bipartition: [ 1, 2, -2 ], [ 3 ], [ 4, 5, 6, -1 ], [ 7 ], [ 8 ], 
 [ -3, -4, -5, -6 ], [ -7 ], [ -8 ]>]]></Example>
  </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsTransBipartition">
  <ManSection>
    <Prop Name="IsTransBipartition" Arg="f"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
    If the bipartition <A>f</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>f</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> f:=Bipartition( [ [ 1, 4, -2 ], [ 2, 5, -6 ], [ 3, -7 ], [ 6, 7, -9 ], 
> [ 8, 9, -1 ], [ 10, -5 ], [ -3 ], [ -4 ], [ -8 ], [ -10 ] ] );;
gap> IsTransBipartition(f);
true
gap> f:=Bipartition( [ [ 1, 4, -3, -6 ], [ 2, 5, -4, -5 ], [ 3, 6, -1 ], 
> [ -2 ] ] );;
gap> IsTransBipartition(f);
false
gap> Number(PartitionMonoid(3), IsTransBipartition);
27]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsPermBipartition">
  <ManSection>
    <Prop Name="IsPermBipartition" Arg="f"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
    If the bipartition <A>f</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> f:=Bipartition( [ [ 1, 4, -1 ], [ 2, -3 ], [ 3, 6, -5 ], 
> [ 5, -2, -4, -6 ] ] );;
gap> IsPermBipartition(f);
false
gap> f:=Bipartition( [ [ 1, -3 ], [ 2, -4 ], [ 3, -6 ], 
> [ 4, -1 ], [ 5, -5 ], [ 6, -2 ], [ 7, -8 ], [ 8, -7 ] ] );;
gap> IsPermBipartition(f);
true]]></Example>
  </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsPartialPermBipartition">
  <ManSection>
    <Prop Name="IsPartialPermBipartition" Arg="f"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
    If the bipartition <A>f</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>f</A> defines a partial permutation if and only if the
    numbers of left and right blocks of <A>f</A> equal the degree of <A>f</A>.

  <Example><![CDATA[
gap> f:=Bipartition( [ [ 1, 4, -1 ], [ 2, -3 ], [ 3, 6, -5 ], 
> [ 5, -2, -4, -6 ] ] );;
gap> IsPartialPermBipartition(f);
false
gap> f:=Bipartition( [ [ 1, -3 ], [ 2 ], [ -4 ], [ 3, -6 ], [ 4, -1 ], 
> [ 5, -5 ], [ 6, -2 ], [ 7, -8 ], [ 8, -7 ] ] );;
gap> IsPermBipartition(f);
false
gap> IsPartialPermBipartition(f); 
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. 
      <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="f, g"/>
    <Returns>A permutation.</Returns>
    <Description>
      If <A>f</A> and <A>g</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>f</A> (and <A>g</A>) induced by 
      <C>Star(<A>f</A>)*<A>g</A></C>. <P/>

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

      The value returned by <C>PermLeftQuoBipartition(<A>f</A>,<A>g</A>)</C> is
      the same as that returned by 
      <C>PermRightBlocks(RightBlocks(<A>f</A>), Star(<A>f</A>)*<A>g</A>)</C>.
      See also <Ref Oper="PermRightBlocks"/> and 
       <Ref Oper="OnRightBlocksBipartitionByPerm"/>.
      <Example><![CDATA[
gap> f:=Bipartition( [ [ 1, 4, 6, 7, 8, 10 ], [ 2, 5, -1, -2, -8 ], 
> [ 3, -3, -6, -7, -9 ], [ 9, -4, -5 ], [ -10 ] ] );;
gap> g:=Bipartition( [ [ 1, 4, 6, 7, 8, 10 ], [ 2, 5, -3, -6, -7, -9 ], 
> [ 3, -4, -5 ], [ 9, -1, -2, -8 ], [ -10 ] ] );;
gap> PermLeftQuoBipartition(f, g);
(1,2,3)
gap> Star(f)*g;
<bipartition: [ 1, 2, 8, -3, -6, -7, -9 ], [ 3, 6, 7, 9, -4, -5 ], 
 [ 4, 5, -1, -2, -8 ], [ 10 ], [ -10 ]>
gap> PermRightBlocks(RightBlocks(f), last);
(1,2,3)]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="OnRightBlocksBipartitionByPerm">
  <ManSection>
    <Func Name="OnRightBlocksBipartitionByPerm" Arg="f, p"/>
    <Returns>A bipartition.</Returns>
    <Description>
      If <A>f</A> is a bipartition and <A>p</A> is a permutation of the
      indices of the right blocks of <A>f</A>, then
      <C>OnRightBlocksBipartitionByPerm</C> returns the bipartition obtained
      from <A>f</A> by rearranging the right blocks of <A>f</A> according to
      <A>p</A>.
      
      <Example><![CDATA[
gap> f:=Bipartition( [ [ 1, 4, 6, 7, 8, 10 ], [ 2, 5, -1, -2, -8 ],
> [ 3, -3, -6, -7, -9 ], [ 9, -4, -5 ], [ -10 ] ] );;
gap> OnRightBlocksBipartitionByPerm(f, (1,2,3));
<bipartition: [ 1, 4, 6, 7, 8, 10 ], [ 2, 5, -3, -6, -7, -9 ], 
 [ 3, -4, -5 ], [ 9, -1, -2, -8 ], [ -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="f"/>
    <Attr Name="NrTransverseBlocks" Arg="f" Label="for a bipartition"/>
    <Returns>The rank of a bipartition.</Returns>
    <Description>
      When the argument is a bipartition <A>f</A>, <C>RankOfBipartition</C>
      returns the number of blocks of <A>f</A> containing both positive and
      negative entries, i.e. the number of transverse blocks of <A>f</A>.<P/>

      <C>NrTransverseBlocks</C> is just a synonym for <C>RankOfBipartition</C>. 
      <Example><![CDATA[
gap> f:=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(f);
4]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="DegreeOfBipartition">
  <ManSection>
    <Attr Name="DegreeOfBipartition" Arg="f"/>
    <Attr Name="DegreeOfBipartitionCollection" Arg="f"/>
    <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>f</A> is a bipartition defined on <C>2*n</C>
points, then the degree of <A>f</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> f:=Bipartition( [ [ 1, 7, -3, -8 ], [ 2, 6 ], [ 3 ], [ 4, -7, -9 ], 
> [ 5, 9, -2 ], [ 8, -1, -4, -6 ], [ -5 ] ] );;
gap> DegreeOfBipartition(f);
9
gap> s:=BrauerMonoid(5);
<regular bipartition monoid on 5 pts 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>f</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> f:=Bipartition( [ [ 1, -1 ],[ 2, 3, -3 ], [ -2 ] ] );
<bipartition: [ 1, -1 ], [ 2, 3, -3 ], [ -2 ]>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

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

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

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

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

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

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

<#GAPDoc Label="RandomBipartition">
  <ManSection>
    <Oper Name="RandomBipartition" Arg="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>.
      <Log><![CDATA[
gap> f:=RandomBipartition(6); 
<bipartition: [ 1, 2, 3, 4 ], [ 5 ], [ 6, -2, -3, -4 ], [ -1, -5 ], [ -6 ]>
]]></Log>
    </Description>
  </ManSection>
<#/GAPDoc>

#EOF
