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

<#GAPDoc Label="ProjectionFromBlocks">
  <ManSection>
    <Attr Name = "ProjectionFromBlocks" Arg = "blocks"/>
    <Returns>A bipartition.</Returns>
    <Description>
      When the argument <A>blocks</A> is the left or right blocks of a
      bipartition, this operation returns the unique bipartition whose left and
      right blocks are equal to <A>blocks</A>. <P/>

      If <A>blocks</A> is the left blocks of a bipartition <C>x</C>, then this
      operation returns a bipartition equal to the left projection of <C>x</C>.
      The analogous statement holds when <A>blocks</A> is the right blocks
      of a bipartition. 

      <Example><![CDATA[
gap> x := Bipartition([[1], [2, -2, -3], [3], [-1]]);
<bipartition: [ 1 ], [ 2, -2, -3 ], [ 3 ], [ -1 ]>
gap> ProjectionFromBlocks(LeftBlocks(x));
<bipartition: [ 1 ], [ 2, -2 ], [ 3 ], [ -1 ], [ -3 ]>
gap> LeftProjection(x);
<bipartition: [ 1 ], [ 2, -2 ], [ 3 ], [ -1 ], [ -3 ]>
gap> ProjectionFromBlocks(RightBlocks(x));
<bipartition: [ 1 ], [ 2, 3, -2, -3 ], [ -1 ]>
gap> RightProjection(x);
<bipartition: [ 1 ], [ 2, 3, -2, -3 ], [ -1 ]>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsBlocks">
  <ManSection>
    <Filt Name = "IsBlocks" Arg = "obj" Type = "Category"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
   Every blocks object in &GAP; belongs to the category
    <C>IsBlocks</C>. Basic operations for blocks are
    <Ref Oper = "ExtRepOfObj" Label = "for a blocks"/>,
    <Ref Attr = "RankOfBlocks"/>,
    <Ref Attr = "DegreeOfBlocks"/>,
    <Ref Oper = "OnRightBlocks"/>, and
    <Ref Oper = "OnLeftBlocks"/>.
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="BLOCKS_NC">
  <ManSection>
    <Func Name = "BLOCKS_NC" Arg = "classes"/>
    <Returns>A blocks.</Returns>
    <Description>
      This function makes it possible to create a &GAP; object corresponding
      to the left or right blocks of a bipartition without reference to any
      bipartitions.
      <P/>

      <C>BLOCKS_NC</C> returns the blocks with equivalence
      classes <A>classes</A>, which should be a list of duplicate-free lists
      consisting solely of positive or negative integers, where the union of the
      absolute values of the lists is <C>[1 .. n]</C> for some <C>n</C>. The
      blocks with positive entries correspond to transverse blocks and the
      classes with negative entries correspond to non-transverse blocks. <P/>

      This method function does not check that its arguments are valid, and
      should be used with caution.

      <Example><![CDATA[
gap> BLOCKS_NC([[1], [2], [-3, -6], [-4, -5]]);
<blocks: [ 1* ], [ 2* ], [ 3, 6 ], [ 4, 5 ]>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="OnRightBlocks">
  <ManSection>
    <Oper Name = "OnRightBlocks" Arg = "blocks, x"/>
    <Returns>The blocks of a bipartition.</Returns>
    <Description>
      <C>OnRightBlocks</C> returns the right blocks of the product
      <C>g * <A>x</A></C> where <C>g</C> is any bipartition whose right blocks
      are equal to <A>blocks</A>. 
      <Example><![CDATA[
gap> x := Bipartition([[1, 4, 5, 8], [2, 3, 7], [6, -3, -4, -5],
>                      [-1, -2, -6], [-7, -8]]);;
gap> y := Bipartition([[1, 5], [2, 4, 8, -2], [3, 6, 7, -3, -4],
>                      [-1, -6, -8], [-5, -7]]);;
gap> RightBlocks(y * x);
<blocks: [ 1, 2, 6 ], [ 3*, 4*, 5* ], [ 7, 8 ]>
gap> OnRightBlocks(RightBlocks(y), x);
<blocks: [ 1, 2, 6 ], [ 3*, 4*, 5* ], [ 7, 8 ]>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="OnLeftBlocks">
  <ManSection>
    <Oper Name = "OnLeftBlocks" Arg = "blocks, x"/>
    <Returns>The blocks of a bipartition.</Returns>
    <Description>
      <C>OnLeftBlocks</C> returns the left blocks of the product <C><A>x</A> *
        y</C> where <C>y</C> is any bipartition whose left blocks are equal to
      <A>blocks</A>. 
      <Example><![CDATA[
gap> x := Bipartition([[1, 5, 7, -1, -3, -4, -6], [2, 3, 6, 8],
>                      [4, -2, -5, -8], [-7]]);;
gap> y := Bipartition([[1, 3, -4, -5], [2, 4, 5, 8], [6, -1, -3],
>                      [7, -2, -6, -7, -8]]);;
gap> LeftBlocks(x * y);
<blocks: [ 1*, 4*, 5*, 7* ], [ 2, 3, 6, 8 ]>
gap> OnLeftBlocks(LeftBlocks(y), x);
<blocks: [ 1*, 4*, 5*, 7* ], [ 2, 3, 6, 8 ]>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="ExtRepOfObjBlocks">
  <ManSection>
    <Oper Name = "ExtRepOfObj" Arg = "blocks" Label = "for a blocks"/>
    <Returns>A list of integers.</Returns>
    <Description>
       If <C>n</C> is the degree of a bipartition with left or right blocks
       <A>blocks</A>, then <C>ExtRepOfObj</C> returns the partition
       corresponding to <A>blocks</A> as a sorted list of duplicate-free lists. 
      <Example><![CDATA[
gap> blocks := BLOCKS_NC([[1, 6], [2, 3, 7], [4, 5], [-8]]);;
gap> ExtRepOfObj(blocks);
[ [ 1, 6 ], [ 2, 3, 7 ], [ 4, 5 ], [ -8 ] ]]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="RankOfBlocks">
  <ManSection>
    <Attr Name = "RankOfBlocks" Arg = "blocks"/>
    <Attr Name = "NrTransverseBlocks" Arg = "blocks" Label = "for blocks"/>
    <Returns>A non-negative integer.</Returns>
    <Description>
      When the argument <A>blocks</A> is the left or right blocks of a
      bipartition, <C>RankOfBlocks</C> returns the number of blocks of
      <A>blocks</A> containing only positive entries, i.e.  the number of
      transverse blocks in <A>blocks</A>. <P/>

      <C>NrTransverseBlocks</C> is a synonym of <C>RankOfBlocks</C> in this
      context. 
      <Example><![CDATA[
gap> blocks := BLOCKS_NC([[-1, -2, -4, -6], [3, 10, 12], [5, 7],
>                        [8], [9], [-11]]);;
gap> RankOfBlocks(blocks);
4]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="DegreeOfBlocks">
  <ManSection>
    <Attr Name = "DegreeOfBlocks" Arg = "blocks"/>
    <Returns>A non-negative integer.</Returns>
    <Description>
      The degree of <A>blocks</A> is the number of points <C>n</C> where
      it is defined, i.e. the union of the blocks in <A>blocks</A> will be
      <C>[1 .. n]</C> after taking the absolute value of every element. 
      <Example><![CDATA[
gap> blocks := BLOCKS_NC([[-1, -11], [2], [3, 5, 6, 7], [4, 8], [9, 10],
>                        [12]]);;
gap> DegreeOfBlocks(blocks);
12]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="CanonicalBlocks">
  <ManSection>
    <Attr Name = "CanonicalBlocks" Arg = "blocks"/>
    <Returns>Blocks of a bipartition.</Returns>
    <Description>
      If <A>blocks</A> is the blocks of a bipartition, then the function
      <C>CanonicalBlocks</C> returns a canonical representative of 
      <A>blocks</A>.
      <P/>

      In particular, let <C>C(n)</C> be a largest class such that any element of
      <C>C(n)</C> is blocks of a bipartition of degree <C>n</C> and such that for
      every pair of elements <C>x</C> and <C>y</C> of <C>C(n)</C> the number of
      signed, and similarly unsigned, blocks of any given size in both <C>x</C>
      and <C>y</C> are the same. Then <C>CanonicalBlocks</C> returns a
      canonical representative of a class <C>C(n)</C> containing <A>blocks</A>
      where <C>n</C> is the degree of <A>blocks</A>.
      <Example><![CDATA[
gap> B := BLOCKS_NC([[-1, -3], [2, 4, 7], [5, 6]]);
<blocks: [ 1, 3 ], [ 2*, 4*, 7* ], [ 5*, 6* ]>
gap> CanonicalBlocks(B);
<blocks: [ 1*, 2* ], [ 3*, 4*, 5* ], [ 6, 7 ]>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>
