Ticket #5790: trac_5790_review_nt.patch

sage/combinat/partition.py

@@ -20 +20 @@
 - Dan Drake (2009-03-28): deprecate RestrictedPartitions and implement
   Partitions_parts_in
 
-EXAMPLES: There are 5 partitions of the integer 4.
+EXAMPLES:
 
-::
+There are 5 partitions of the integer 4::
 
     sage: Partitions(4).cardinality()
     5
@@ -30 +30 @@
     [[4], [3, 1], [2, 2], [2, 1, 1], [1, 1, 1, 1]]
 
 We can use the method .first() to get the 'first' partition of a
-number.
-
-::
+number::
 
     sage: Partitions(4).first()
     [4]
 
 Using the method .next(), we can calculate the 'next' partition.
-When we are at the last partition, None will be returned.
-
-::
+When we are at the last partition, None will be returned::
 
     sage: Partitions(4).next([4])
     [3, 1]
@@ -48 +44 @@
     True
 
 We can use ``iter`` to get an object which iterates over the partitions one
-by one to save memory.  Note that when we do something like 
-``for part in Partitions(4)`` this iterator is used in the background.
-  
-::
+by one to save memory.  Note that when we do something like
+``for part in Partitions(4)`` this iterator is used in the background::
 
     sage: g = iter(Partitions(4))
 
@@ -95 +89 @@
 
 The min_part options is complementary to max_part and selects
 partitions having only 'large' parts. Here is the list of all
-partitions of 4 with each part at least 2.
-
-::
+partitions of 4 with each part at least 2::
 
     sage: Partitions(4, min_part=2).list()
     [[4], [2, 2]]
@@ -119 +111 @@
 
 Finally, here are the partitions of 4 with [1,1,1] as an inner
 bound. Note that inner sets min_length to the length of its
-argument.
-
-::
+argument::
 
     sage: Partitions(4, inner=[1,1,1]).list()
     [[2, 1, 1], [1, 1, 1, 1]]
@@ -143 +133 @@
     [[7, 4], [6, 5], [6, 4, 1], [6, 3, 2], [5, 4, 2], [5, 3, 2, 1]]
 
 Partition objects can also be created individually with the
-Partition function.
-
-::
+Partition function::
 
     sage: Partition([2,1])
     [2, 1]
@@ -154 +142 @@
 methods that we can use. For example, we can get the conjugate of a
 partition. Geometrically, the conjugate of a partition is the
 reflection of that partition through its main diagonal. Of course,
-this operation is an involution.
-
-::
+this operation is an involution::
 
     sage: Partition([4,1]).conjugate()
     [2, 1, 1, 1]
@@ -165 +151 @@
 
 We can go back and forth between the exponential notations of a
 partition. The exponential notation can be padded with extra
-zeros.
-
-::
+zeros::
 
     sage: Partition([6,4,4,2,1]).to_exp()
     [1, 1, 0, 2, 0, 1]
@@ -180 +164 @@
     sage: Partition([6,4,4,2,1]).to_exp(10)
     [1, 1, 0, 2, 0, 1, 0, 0, 0, 0]
 
-We can get the coordinates of the corners of a partition.
-
-::
+We can get the coordinates of the corners of a partition::
 
     sage: Partition([4,3,1]).corners()
     [[0, 3], [1, 2], [2, 0]]
 
 We can compute the core and quotient of a partition and build
-the partition back up from them.
-
-::
+the partition back up from them::
 
     sage: Partition([6,3,2,2]).core(3)
     [2, 1, 1]
@@ -208 +188 @@
 #       Copyright (C) 2007 Mike Hansen <mhansen@gmail.com>, 
 #
 #  Distributed under the terms of the GNU General Public License (GPL)
-#
-#    This code is distributed in the hope that it will be useful,
-#    but WITHOUT ANY WARRANTY; without even the implied warranty of
-#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-#    General Public License for more details.
-#
-#  The full text of the GPL is available at:
-#
 #                  http://www.gnu.org/licenses/
 #*****************************************************************************
 
 from sage.interfaces.all import gap, gp
 from sage.rings.all import QQ, ZZ, infinity, factorial, gcd
-from sage.misc.all import prod, sage_eval
+from sage.misc.all import prod
 from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing
 import sage.combinat.misc as misc
 import sage.combinat.skew_partition
@@ -239 +211 @@
 from integer_list import IntegerListsLex
 from sage.functions.other import ceil
 
-def Partition(mu=None, **key_word):                                              
-    """                                                                          
-    A partition is a weakly decreasing ordered sequence of non-negative          
-    integers. This function returns a Sage partition object which can            
-    be specified in one of the following ways::                                  
-      * a list (the default)                                                     
-      * using exponential notation                                               
-      * by beta numbers (TODO)                                                   
-      * specifying the core and the quotient                                     
-      * specifying the core and the canonical quotient (TODO)                    
-    See the examples below.                                                      
-                                                                                 
-    Sage follows the usual python conventions when dealing with partitions,      
-    so that the first part of the partition ``mu=Partition([4,3,2,2])`` is       
-    ``mu[0]``, the second part is ``mu[1]`` and so on. As is usual, Sage ignores 
-    trailing zeros at the end of partitions.                                     
-                                                                                 
-    EXAMPLES::                                                                   
-                                                                                 
-        sage: Partition([3,2,1])                                                 
-        [3, 2, 1]                                                                
-        sage: Partition([3,2,1,0])                                               
-        [3, 2, 1]                                                                
+def Partition(mu=None, **keyword):
+    """
+    A partition is a weakly decreasing ordered sequence of non-negative
+    integers. This function returns a Sage partition object which can
+    be specified in one of the following ways::
+
+      * a list (the default)
+      * using exponential notation
+      * by beta numbers (TODO)
+      * specifying the core and the quotient
+      * specifying the core and the canonical quotient (TODO)
+
+    See the examples below.
+
+    Sage follows the usual python conventions when dealing with partitions,
+    so that the first part of the partition ``mu=Partition([4,3,2,2])`` is
+    ``mu[0]``, the second part is ``mu[1]`` and so on. As is usual, Sage ignores
+    trailing zeros at the end of partitions.
+
+    EXAMPLES::
+
+        sage: Partition([3,2,1])
+        [3, 2, 1]
+        sage: Partition([3,2,1,0])
+        [3, 2, 1]
         sage: Partition(exp=[2,1,1])
         [3, 2, 1, 1]
         sage: Partition(core=[2,1], quotient=[[2,1],[3],[1,1,1]])
@@ -275 +249 @@
         ...
         ValueError: [1, 2, 3] is not a valid partition
     """
-    if mu is not None and len(key_word)==0:
+    if mu is not None and len(keyword)==0:
         mu = [i for i in mu if i != 0]
         if mu in Partitions_all():
             return Partition_class(mu)
         else:
             raise ValueError, "%s is not a valid partition"%mu
-    elif 'beta_numbers' in key_word and len(key_word)==1:
+    elif 'beta_numbers' in keyword and len(keyword)==1:
         raise NotImplementedError
-    elif 'exp' in key_word and len(key_word)==1:
-        return from_exp(key_word['exp'])
-    elif 'core' in key_word and 'quotient' in key_word and len(key_word)==2:
-        return from_core_and_quotient(key_word['core'], key_word['quotient'])
-    elif 'core' in key_word and 'canonical_quotient' in key_word and len(key_word)==2:
+    elif 'exp' in keyword and len(keyword)==1:
+        return from_exp(keyword['exp'])
+    elif 'core' in keyword and 'quotient' in keyword and len(keyword)==2:
+        return from_core_and_quotient(keyword['core'], keyword['quotient'])
+    elif 'core' in keyword and 'canonical_quotient' in keyword and len(keyword)==2:
         raise NotImplementedError
-    elif 'core_and_quotient' in key_word and len(key_word)==1:
+    elif 'core_and_quotient' in keyword and len(keyword)==1:
         from sage.misc.misc import deprecation
         deprecation('"core_and_quotient=(*)" is deprecated. Use "core=[*], quotient=[*]" instead.')
-        return from_core_and_quotient(*key_word['core_and_quotient'])
+        return from_core_and_quotient(*keyword['core_and_quotient'])
     else:
         raise ValueError, 'incorrect syntax for Partition()'
 
@@ -304 +278 @@
 
        This function is for internal use only; 
        use Partition(exp=*) instead.
-    
+
     EXAMPLES::
-    
+
         sage: Partition(exp=[1,2,1])
         [3, 2, 2, 1]
     """
@@ -318 +292 @@
 def from_core_and_quotient(core, quotient):
     """
     ** This function is being deprecated - use Partition(core=*, quotient=*) instead **
-    
+
     Returns a partition from its core and quotient.
     
     Algorithm from mupad-combinat.
@@ -327 +301 @@
 
        This function is for internal use only; 
        use Partition(core=*, quotient=*) instead.
-    
+
     EXAMPLES::
-    
+
         sage: Partition(core=[2,1], quotient=[[2,1],[3],[1,1,1]])
         [11, 5, 5, 3, 2, 2, 2]
     """
@@ -397 +371 @@
 
         return sage.combinat.skew_partition.SkewPartition([self[:], p])
         
-    def power(self,k):
+    def power(self, k):
         """
-        partition_power( pi, k ) returns the partition corresponding to
-        the `k`-th power of a permutation with cycle structure pi
-        (thus describes the powermap of symmetric groups).
+        Returns the cycle type of the `k`-th power of any permutation
+        with cycle type ``self`` (thus describes the powermap of
+        symmetric groups).
         
         Wraps GAP's PowerPartition.
         
@@ -514 +488 @@
 
     def sign(self):
         r"""
-        Returns the sign of a permutation with cycle type of the partition.
+        Returns the sign of any permutation with cycle type ``self``.
         
         This function corresponds to a homomorphism from the symmetric
         group `S_n` into the cyclic group of order 2, whose kernel
@@ -1267 +1241 @@
     def centralizer_size(self, t=0, q=0):
         """
         Returns the size of the centralizer of any permutation of cycle type
-        p. If m_i is the multiplicity of i as a part of p, this is given
+        ``self``. If m_i is the multiplicity of i as a part of p, this is given
         by `\prod_i (i^m[i])*(m[i]!)`. Including the optional
         parameters t and q gives the q-t analog which is the former product
         times `\prod_{i=1}^{length(p)} (1 - q^{p[i]}) / (1 - t^{p[i]}).`
@@ -1294 +1268 @@
     def aut(self):
         r"""
         Returns a factor for the number of permutations with cycle type
-        self. self.aut() returns
+        ``self``. self.aut() returns
         `1^{j_1}j_1! \cdots n^{j_n}j_n!` where `j_k`
         is the number of parts in self equal to k.
         
@@ -1417 +1391 @@
         return res
 
     def r_core(self, length):
-      """ *** deprecate *** """
-      from sage.misc.misc import deprecation
-      deprecation('r_core is deprecated. Use core instead.')
-      return self.core(self, length)
+        """
+        This function is deprecated.
+
+        EXAMPLES::
+
+            sage: Partition([6,3,2,2]).r_core(3)
+            doctest:1: DeprecationWarning: r_core is deprecated. Please use core instead.
+            [2, 1, 1]
+
+        Please use :meth:`core` instead::
+
+            sage: Partition([6,3,2,2]).core(3)
+            [2, 1, 1]
+
+        """
+        from sage.misc.misc import deprecation
+        deprecation('r_core is deprecated. Please use core instead.')
+        return self.core(length)
 
     def core(self, length):
         """
         Returns the core of the partition -- in the literature the core is
-        commonly referred to as the k-core, p-core, r-core, ... . The
+        commonly referred to as the `k`-core, `p`-core, `r`-core, ... . The
         construction of the core can be visualized by repeatedly removing
-        border strips of size r from p until this is no longer possible.
+        border strips of size `r` from ``self`` until this is no longer possible.
         The remaining partition is the core.
-        
+
         EXAMPLES::
-        
+
             sage: Partition([6,3,2,2]).core(3)
             [2, 1, 1]
             sage: Partition([]).core(3)
             []
             sage: Partition([8,7,7,4,1,1,1,1,1]).core(3)
             [2, 1, 1]
-        
+
         TESTS::
-        
+
             sage: Partition([3,3,3,2,1]).core(3)
             []
             sage: Partition([10,8,7,7]).core(4)
@@ -1471 +1459 @@
         return filter(lambda x: x != 0, part)
 
     def r_quotient(self, length):
-        """ *** deprecate *** """
-        from sage.misc.misc import deprecation
-        deprecation('r_quotient is deprecated. Use quotient instead.')
-        return self.quotient(self,length)
+        """
+        This function is deprecated.
+
+        EXAMPLES::
+
+            sage: Partition([6,3,2,2]).r_quotient(3)
+            doctest:1: DeprecationWarning: r_quotient is deprecated. Please use quotient instead.
+            [[], [], [2, 1]]
 
+        Please use :meth:`quotient` instead::
+
+            sage: Partition([6,3,2,2]).quotient(3)
+            [[], [], [2, 1]]
+        """
+        from sage.misc.misc import deprecation
+        deprecation('r_quotient is deprecated. Please use quotient instead.')
+        return self.quotient(length)
 
     def quotient(self, length):
         """
         Returns the quotient of the partition  -- in the literature the
-        core is commonly referred to as the k-core, p-core, r-core, ... . The
-        quotient is a list of r partitions, constructed in the following
-        way. Label each cell in p with its content, modulo r. Let R_i be
-        the set of rows ending in a box labelled i, and C_i be the set of
-        columns ending in a box labelled i. Then the jth component of the
-        quotient of p is the partition defined by intersecting R_j with
-        C_j+1.
-        
+        core is commonly referred to as the `k`-core, `p`-core, `r`-core, ... . The
+        quotient is a list of `r` partitions, constructed in the following
+        way. Label each cell in `p` with its content, modulo `r`. Let `R_i` be
+        the set of rows ending in a box labelled `i`, and `C_i` be the set of
+        columns ending in a box labelled `i`. Then the `j`-th component of the
+        quotient of `p` is the partition defined by intersecting `R_j` with
+        `C_j+1`.
+
         EXAMPLES::
 
             sage: Partition([7,7,5,3,3,3,1]).quotient(3)
@@ -4251 +4251 @@
 def partition_power(pi,k):
     """
     partition_power( pi, k ) returns the partition corresponding to
-    the `k`-th power of a permutation with cycle structure pi
+    the `k`-th power of a permutation with cycle structure ``pi``
     (thus describes the powermap of symmetric groups).
     
     Wraps GAP's PowerPartition.
@@ -4295 +4295 @@
     is exactly the alternating group `A_n`. Partitions of sign
     `1` are called even partitions while partitions of sign
     `-1` are called odd.
-   
+
     This function is deprecated: use Partition( pi ).sign() instead.
 
     EXAMPLES::
-    
+
         sage: Partition([5,3]).sign()
         1
         sage: Partition([5,2]).sign()
@@ -4390 +4390 @@
     from sage.misc.misc import deprecation
     deprecation('"partition_associated deprecated. Use Partition(pi).conjugte() instead')
     return Partition(pi).conjugate()
-            
+