Ticket #8420: trac_8420_perfect_matchings_review-fh.patch

File trac_8420_perfect_matchings_review-fh.patch, 10.0 KB (added by hivert, 12 years ago)

  • sage/combinat/perfect_matching.py 

    # HG changeset patch
# User Florent Hivert <Florent.Hivert@univ-rouen.fr>
# Date 1268669308 -3600
# Node ID f815c9f725ca00c20501036dac7b941adccf6c48
# Parent  6d2612bf6089bfddc16907dd238dfae1d63a576c
8420: Review: Better ReSTification of the doc.
              Removed unused __init__
	      Added and moved a few tests.

diff --git a/sage/combinat/perfect_matching.py b/sage/combinat/perfect_matching.py
    a b  
    11r"""
    22Perfect matchings
    33
    4 A perfect matching of a set `S` is a partition into 2-element sets. If `S`is
    5 the set `{1,..,n}`, it is equivalent to fixpoint-free involutions. These simple
    6 combinatorial objects appear in different domains:
    7 
    8     - combinatorics of orthogonal polynomials (A. de Medicis et X.Viennot,
    9     Moments des q-polynomes de Laguerre et la bijection de Foata-Zeilberger,
    10     Adv. Appl. Math., 15 (1994), 262-304)
    11 
    12     - combinatorics of hyperoctahedral group, double coset algebra and zonal
    13     polynomials (I. G. Macdonald, Symmetric functions and Hall polynomials,
    14     Oxford University Press, second edition, 1995, chapter VII).
     4A perfect matching of a set `S` is a partition into 2-element sets. If `S` is
     5the set `\{1,...,n\}`, it is equivalent to fixpoint-free involutions. These
     6simple combinatorial objects appear in different domains such as combinatoric
     7of orthogonal polynomials and of the hyperoctaedral groups (see [MV]_, [McD]_
     8and also [CM]_):
    159
    1610AUTHOR:
    1711
    … … EXAMPLES: 
    3630        sage: PerfectMatchings(4).list()
    3731        [PerfectMatching [(4, 1), (3, 2)], PerfectMatching [(4, 2), (3, 1)], PerfectMatching [(4, 3), (2, 1)]]
    3832
     33REFERENCES:
     34
     35    .. [MV] combinatorics of orthogonal polynomials (A. de Medicis et
     36       X.Viennot, Moments des q-polynomes de Laguerre et la bijection de
     37       Foata-Zeilberger, Adv. Appl. Math., 15 (1994), 262-304)
     38
     39    .. [McD] combinatorics of hyperoctahedral group, double coset algebra and
     40       zonal polynomials (I. G. Macdonald, Symmetric functions and Hall
     41       polynomials, Oxford University Press, second edition, 1995, chapter
     42       VII).
     43
     44    .. [CM] Benoit Collins, Sho Matsumoto, On some properties of
     45       orthogonal Weingarten functions, arXiv:0903.5143.
     46"""
     47
    3948#*****************************************************************************
    4049#       Copyright (C) 2010 Valentin Feray <feray@labri.fr>
    4150#
    … … EXAMPLES: 
    4352#                  http://www.gnu.org/licenses/
    4453#*****************************************************************************
    4554
    46 """
    4755
    4856#from sage.combinat.permutation import Permutation_Class
    4957from sage.structure.unique_representation import UniqueRepresentation
    … … class PerfectMatching(ElementWrapper): 
    127135        matching (i.e. a list of pairs with pairwise disjoint elements  or a
    128136        fixpoint-free involution) and raises a ValueError otherwise:
    129137
    130             sage: try:
    131             ...    m=PerfectMatching([(1, 2, 3), (4, 5)])
    132             ... except ValueError:
    133             ...    "A ValueError has been raised."
    134             'A ValueError has been raised.'
    135        
     138            sage: PerfectMatching([(1, 2, 3), (4, 5)])
     139            Traceback (most recent call last):
     140            ...
     141            ValueError: [(1, 2, 3), (4, 5)] is not a valid perfect matching: all elements of the list must be pairs
     142
    136143        If you know your datas are in a good format, use directly
    137         `PerfectMatchings(objects)(data)`.         
     144        `PerfectMatchings(objects)(data)`.
     145
     146        TESTS::
     147
     148             sage: m=PerfectMatching([('a','e'),('b','c'),('d','f')])
     149             sage: TestSuite(m).run()
     150             sage: m=PerfectMatching([])
     151             sage: TestSuite(m).run()
    138152        """
    139153        # we have to extract from the argument p the set of objects of the
    140154        # matching and the list of pairs.
    … … class PerfectMatching(ElementWrapper): 
    171185        # executed and we do not have an infinite loop.
    172186        return PerfectMatchings(objects)(data)
    173187
    174     def __init__(self,data,parent):
    175         r"""
    176         See :meth:`__classcall_private__`
    177 
    178         TESTS::
    179 
    180             sage: m=PerfectMatching([('a','e'),('b','c'),('d','f')])
    181             sage: TestSuite(m).run()
    182         """
    183         self.value=data
    184         Element.__init__(self,parent=parent)
    185 
    186188    def _repr_(self):
    187189        r"""
    188190        returns the name of the object
    … … class PerfectMatching(ElementWrapper): 
    272274        INPUT:
    273275
    274276             - ``other`` -- a perfect matching of the same set of ``self``.
    275              (if the second argument is empty, the method :meth:`an_element` is
    276              called on the parent of the first)
     277               (if the second argument is empty, the method :meth:`an_element` is
     278               called on the parent of the first)
    277279
    278280        OUTPUT:
    279281
    … … class PerfectMatching(ElementWrapper): 
    320322        INPUT:
    321323
    322324             - ``other`` -- a perfect matching of the same set of ``self``.
    323              (if the second argument is empty, the method :meth:`an_element` is
    324              called on the parent of the first)
     325               (if the second argument is empty, the method :meth:`an_element` is
     326               called on the parent of the first)
    325327
    326328        OUTPUT:
    327329
    … … class PerfectMatching(ElementWrapper): 
    348350        INPUT:
    349351
    350352             - ``other`` -- a perfect matching of the same set of ``self``.
    351              (if the second argument is empty, the method :meth:`an_element` is
    352              called on the parent of the first)
     353               (if the second argument is empty, the method :meth:`an_element` is
     354               called on the parent of the first)
    353355
    354356        OUTPUT:
    355357
    … … class PerfectMatching(ElementWrapper): 
    378380        INPUT:
    379381
    380382            - ``other`` -- a perfect matching of the same set of ``self``.
    381             (if the second argument is empty, the fonction an_element is
    382             called on the parent of the first)
     383              (if the second argument is empty, the method :meth:`an_element` is
     384              called on the parent of the first)
    383385
    384386        OUTPUT:
    385387
    … … class PerfectMatching(ElementWrapper): 
    654656
    655657    def Weingarten_function(self,d,other=None):
    656658        r"""
    657         Returns the Weingarten function of two pairings. This function is
    658         the value of some integrals over the orhtogonal groups `O_N`
    659        
    660         Reference : Benoit Collins, Sho Matsumoto, On some properties of
    661         orthogonal Weingarten functions, arXiv:0903.5143
    662         With the convention of this article, the function returns
     659        Returns the Weingarten function of two pairings.
     660
     661        This function is the value of some integrals over the orhtogonal
     662        groups `O_N`.  With the convention of [CM]_, the method returns
    663663        `Wg^{O(d)}(other,self)`.
    664664
    665665        EXAMPLES::
    … … class PerfectMatchings(UniqueRepresentat 
    705705
    706706        sage: PerfectMatchings(5).list()
    707707        []
     708        sage: TestSuite(PerfectMatchings(5)).run()
     709        sage: TestSuite(PerfectMatchings([])).run()
    708710    """
    709711
    710712    @staticmethod
    … … class PerfectMatchings(UniqueRepresentat 
    880882        r"""
    881883        Returns the Weingarten matrix corresponding to the set of
    882884        PerfectMatchings ``self``. It is a useful theoretical tool to compute
    883         polynomial integral over the orthogonal group `O_N`.
    884 
    885         Reference : Benoit Collins, Sho Matsumoto, On some properties of
    886         orthogonal Weingarten functions, arXiv:0903.5143
     885        polynomial integral over the orthogonal group `O_N` (see [CM]_).
    887886
    888887        EXAMPLES::
    889888

  • sage/combinat/permutation.py 

    diff --git a/sage/combinat/permutation.py b/sage/combinat/permutation.py
    a b class Permutation_class(CombinatorialObj 
    26162616                break
    26172617            i -= 1
    26182618        return Permutation_class(self[:i+1])                   
    2619        
    2620     def coset_type(self):
     2619
     2620    def hyperoctahedral_double_coset_type(self):
     2621        r"""
     2622        Returns the coset type of ``self`` as a
     2623        :mod:`perfect matching <sage.combinat.perfect_matching>`.
     2624
     2625        ``self`` must be a permutation of even size `2n`.  The coset-type
     2626        determines the double class of the permutation, that is its image in
     2627        `H_n \backslash S_2n / H_n`, where `H_n` is the hyperoctahedral group of order
     2628        `n` (see [Mcd]_ for more details). It is returned as an instance of
     2629        :class:`PerfectMatching <sage.combinat.perfect_matching.PerfectMatching>`.
     2630
     2631        EXAMPLE::
     2632
     2633            sage: Permutation([3, 4, 6, 1, 5, 7, 2, 8]).hyperoctahedral_double_coset_type()
     2634            [3, 1]
     2635            sage: all([p.hyperoctahedral_double_coset_type() ==
     2636            ...        p.inverse().hyperoctahedral_double_coset_type()
     2637            ...         for p in Permutations(4)])
     2638            True
     2639            sage: Permutation([]).hyperoctahedral_double_coset_type()
     2640            []
     2641
     2642        REFERENCES:
     2643
     2644            .. [Mcd] I. G. Macdonald, Symmetric functions and Hall
     2645               polynomials, Oxford University Press, second edition, 1995
     2646               (chapter VII).
     2647        """
    26212648        from sage.combinat.perfect_matching import PerfectMatchings
    2622         r"""       
    2623         returns the coset type of ``self``, which must be a permutation of even
    2624         size `2n`. The coset-type determines the double class of the
    2625         permutation, that is its image in `H_n \ S_2n / H_n`, where `H_n` is the
    2626         hyperoctahedral group of order `n`. See I. G. Macdonald, Symmetric
    2627         functions and Hall polynomials, Oxford University Press, second edition,
    2628         1995 (chapter VII) for more details.
    2629 
    2630         EXAMPLE::
    2631 
    2632             sage: Permutation([3, 4, 6, 1, 5, 7, 2, 8]).coset_type()
    2633             [3, 1]
    2634             sage: all([p.coset_type()==p.inverse().coset_type()
    2635             ...         for p in Permutations(4)])
    2636             True
    2637         """
    26382649        n = len(self)
    26392650        if n%2==1:
    26402651            raise ValueError, "%s is a permutation of odd size and has no coset-type"%p