Ticket #8420: trac_8420_features_perfect_matchings_vf.patch

sage/combinat/all.py

@@ -18 +18 @@
 from yang_baxter_graph import YangBaxterGraph
 #from hall_littlewood import HallLittlewood_qp, HallLittlewood_q, HallLittlewood_p
 
+#Permutations
 from permutation import Permutation, Permutations, Arrangements, PermutationOptions, CyclicPermutations, CyclicPermutationsOfPartition
 
+#PerfectMatchings
+from perfect_matching import PerfectMatching, PerfectMatchings
+
 # Integer lists lex
 
 from integer_list import IntegerListsLex

new file sage/combinat/perfect_matching.py

@@ +1 @@
+#from sage.combinat.permutation import Permutation_Class
+from sage.structure.unique_representation import UniqueRepresentation
+from sage.structure.parent import Parent
+from sage.categories.finite_enumerated_sets import FiniteEnumeratedSets
+from sage.misc.classcall_metaclass import ClasscallMetaclass
+from sage.structure.element_wrapper import ElementWrapper
+from sage.structure.element import Element
+from sage.misc.cachefunc import cached_method
+from sage.rings.integer import Integer
+
+class PerfectMatching(ElementWrapper):
+    r"""
+    Class of perfect matching.
+
+    An instance of the class can be created from a list of pairs or from a fixed point-free involution as follows::
+
+        sage: m=PerfectMatching([('a','e'),('b','c'),('d','f')]);m
+        PerfectMatching [('a', 'e'), ('b', 'c'), ('d', 'f')]
+        sage: n=PerfectMatching([3,8,1,7,6,5,4,2]);n
+        PerfectMatching [(1, 3), (2, 8), (4, 7), (5, 6)]
+        sage: isinstance(m,PerfectMatching)
+        True
+
+    The parent, which is the set of perfect matching of the ground set, is automaticly created::
+
+        sage: n.parent()
+        Set of perfect matchings of {1, 2, 3, 4, 5, 6, 7, 8}
+
+    If the ground set is ordered, one can, for example, ask if the matching is non crossing::
+
+        sage: PerfectMatching([(1, 4), (2, 3), (5, 6)]).is_non_crossing()
+        True
+    """
+    #the data structure of the element is a list (accessible via x.value)
+    wrapper_class = list
+    __lt__ = ElementWrapper._lt_by_value
+    #During the creation of the instance of the class, the function __classcall_private__ will be called instead of __init__ directly.
+    __metaclass__ = ClasscallMetaclass
+
+    @staticmethod
+    def __classcall_private__(cls,p):
+        from sage.combinat.permutation import Permutation
+        from sage.misc.flatten import flatten
+        r"""
+        This function tries to recognize the input (it can be either a list or a tuple of pairs, or a fix-point free involution given as a list or as a permutation), constructs the parent (enumerated set of PerfectMatchings of the ground set) and calls the __init__ function to construct our object.
+
+        EXAMPLES::
+
+            sage: m=PerfectMatching([('a','e'),('b','c'),('d','f')]);m
+            PerfectMatching [('a', 'e'), ('b', 'c'), ('d', 'f')]
+            sage: isinstance(m,PerfectMatching)
+            True
+            sage: n=PerfectMatching([3,8,1,7,6,5,4,2]);n
+            PerfectMatching [(1, 3), (2, 8), (4, 7), (5, 6)]
+            sage: n.parent()
+            Set of perfect matchings of {1, 2, 3, 4, 5, 6, 7, 8}
+            sage: PerfectMatching([(1, 4), (2, 3), (5, 6)]).is_non_crossing()
+            True
+
+        TESTS::
+
+            sage: TestSuite(m).run()
+        """
+        #we have to extract from the argument p the set of objects of the matching and the list of pairs
+        #First case: p is a list (resp tuple) of lists (resp tuple).
+        if (isinstance(p,list) or isinstance(p,tuple)) and (
+                all([isinstance(x,list) or isinstance(x,tuple) for x in p])):
+            objects=flatten(p)
+            data=(map(tuple,p))
+        #Second case: p is a permutation or a list of integers, we have to check if it is a fix-point-free involution.
+        elif ((isinstance(p,list) and all(map(lambda x: (isinstance(x,Integer) or isinstance(x,int)),p )))
+                or isinstance(p,sage.combinat.permutation.Permutation_class)):
+            p=Permutation(p)
+            n=len(p)
+            if not(p.cycle_type()==[2 for i in range(n//2)]):
+                raise ValueError, "The permutation p (= %s) is not a fix-point-free involution"%p
+            objects=range(1,n+1)
+            data=p.to_cycles()
+        #Third case: p is already a perfect matching
+        elif isinstance(p,PerfectMatching):
+            data=p.value
+            objects=flatten(data)
+        else:
+            raise ValueError, "cannot convert p (= %s) to a PerfectMatching"%p
+        #Finally, we create the parent and the element using the element class of the parent. Note: as this function is private, when we create an object via parent.element_class(...), __init__ is directly executed and we do not have an infinite loop.
+        parent=PerfectMatchings(objects)
+        return parent.element_class(data,parent)      
+
+    def __init__(self,data,parent):
+        r"""
+        see __classcall_private__?
+        """
+        self.value=data
+        Element.__init__(self,parent=parent)
+
+    def _repr_(self):
+        r"""
+        returns the name of the object
+
+        EXAMPLES::
+
+            sage: m=PerfectMatching([('a','e'),('b','c'),('d','f')]);m
+            PerfectMatching [('a', 'e'), ('b', 'c'), ('d', 'f')]
+            sage: n=PerfectMatching([3,8,1,7,6,5,4,2]);n
+            PerfectMatching [(1, 3), (2, 8), (4, 7), (5, 6)]
+        """
+        return 'PerfectMatching %s'%self.value
+
+    def __eq__(self,other):
+        from sage.sets.set import Set
+        r"""
+        Compares two perfect matchings
+
+        EXAMPLES::
+
+            sage: m=PerfectMatching([('a','e'),('b','c'),('d','f')])
+            sage: n=PerfectMatching([('c','b'),('d','f'),('e','a')])
+            sage: n==m
+            True
+            sage: n==PerfectMatching([('a','b'),('d','f'),('e','c')])
+            False
+
+        """
+        try:
+            if other.parent() <> self.parent():
+                return False
+        except AttributeError:
+            return False
+        return Set(map(Set,self.value))==Set(map(Set,other.value))
+
+    def size(self):
+        r"""
+        returns the size of the perfect matching, i.e. the number of elements in the ground set.
+        
+        EXAMPLES::
+            
+            sage: m=PerfectMatching([(-3, 1), (2, 4), (-2, 7)]); m.size()
+            6
+        """
+        return 2*len(self.value)
+
+    def partner(self,x):
+        r"""
+        Returns the element in the same pair than x in the mathching `self`.
+
+        EXAMPLES::
+            
+            sage: m=PerfectMatching([(-3, 1), (2, 4), (-2, 7)]); m.partner(4)
+            2
+            sage: n=PerfectMatching([('c','b'),('d','f'),('e','a')]); n.partner('c')
+            'b'
+        """
+        for i in range(self.size()):
+            if self.value[i][0]==x:
+                return self.value[i][1]
+            if self.value[i][1]==x:
+                return self.value[i][0]
+        raise ValueError,"%s in not an element of the %s"%(x,self)
+
+    def loop_type(self,other=None):
+        from sage.combinat.permutation import Permutation
+        from sage.combinat.partition import Partition
+        r"""
+        input:
+
+            two perfect matchings of the same set (if the second argument is empty, the fonction an_element is called on the parent of the first)
+
+        output:
+
+            if we draw the two perfect matchings simultaneously as edges of a graph, the graph obtained is a union of cycles of even lengths. The function returns the ordered list of the semi-length of these cycles (considered as a partition)
+
+        EXAMPLES::
+
+            sage: m=PerfectMatching([('a','e'),('b','c'),('d','f')])
+            sage: n=PerfectMatching([('a','b'),('d','f'),('e','c')])
+            sage: m.loop_type(n)
+            [2, 1]
+        """
+        if other is None:
+            other=self.parent().an_element()
+        elif self.parent() <> other.parent():
+            raise ValueError,"%s is not a matching of the ground set of %s"%(other,self)
+        n=self.size()
+        A2N=dict([(self.parent()._objects[i],i+1) for i in range(n)])
+        permself=Permutation(map(lambda x:tuple(map(lambda a:A2N[a],x)),
+                self.value))
+        permother=Permutation(map(lambda x:tuple(map(lambda a:A2N[a],x)),
+                other.value))
+        part=(permself*permother).cycle_type()
+        part_exp=part.to_exp()
+        l=[]
+        for i in range(max(part),0,-1):
+            for j in range(part_exp[i-1]//2):
+                l.append(i)
+        return Partition(l)
+
+    def number_of_loops(self,other=None):
+        r"""
+        input:
+
+            two perfect matchings of the same set (if the second argument is empty, the fonction an_element is called on the parent of the first)
+
+        output:
+
+            if we draw the two perfect matchings simultaneously as edges of a graph, the graph obtained is a union of cycles of even lengths. The function returns their numbers
+
+        EXAMPLES::
+
+            sage: m=PerfectMatching([('a','e'),('b','c'),('d','f')])
+            sage: n=PerfectMatching([('a','b'),('d','f'),('e','c')])
+            sage: m.number_of_loops(n)
+            2
+        """
+        return len(self.loop_type(other))
+
+    def crossings(self):
+        r"""
+        input:
+
+            A perfect matching on an *totally ordered* ground set.
+
+        output:
+
+            We place the element of a ground set and draw the perfect matching by linking the elements of the same pair in the upper half-plane. This function returns the list of the pairs of crossing lines (as a line correspond to a pair, it returns a list of pairs of pairs).
+
+        EXAMPLES::
+
+            sage: n=PerfectMatching([3,8,1,7,6,5,4,2]); n
+            PerfectMatching [(1, 3), (2, 8), (4, 7), (5, 6)]
+            sage: n.crossings()
+            [((1, 3), (2, 8))]
+        """
+        x=self.value[:]
+        if len(x)==0:
+            return []
+        (i,j)=x.pop(0)
+        res=PerfectMatching(x).crossings()
+        for (a,b) in x:
+            if (i<a<j<b) or (i<b<j<a) or (j<a<i<b) or (j<b<i<a) or (
+                    a<i<b<j) or (a<j<b<i) or (b<i<a<j) or (b<j<a<i):
+                res.append(((i,j),(a,b)))
+        return res
+
+    def number_of_crossings(self):
+        r"""
+        input:
+
+            A perfect matching on an *totally ordered* ground set.
+
+        output:
+
+            We place the element of a ground set and draw the perfect matching by linking the elements of the same pair in the upper half-plane. This function returns the number the pairs of crossing lines.
+
+        EXAMPLES::
+
+            sage: n=PerfectMatching([3,8,1,7,6,5,4,2]); n
+            PerfectMatching [(1, 3), (2, 8), (4, 7), (5, 6)]
+            sage: n.number_of_crossings()
+            1
+        """
+        x=self.value[:]
+        if len(x)==0:
+            return 0
+        (i,j)=x.pop(0)
+        res=PerfectMatching(x).number_of_crossings()
+        for (a,b) in x:
+            if (i<a<j<b) or (i<b<j<a) or (j<a<i<b) or (j<b<i<a) or (
+                    a<i<b<j) or (a<j<b<i) or (b<i<a<j) or (b<j<a<i):
+                res+=1
+        return res
+
+    def is_non_crossing(self):
+        r"""
+        input:
+
+            A perfect matching on an *totally ordered* ground set.
+
+        output:
+
+            We place the element of a ground set and draw the perfect matching by linking the elements of the same pair in the upper half-plane. This function returns True if the picture obtained this way has no crossings.
+
+        EXAMPLES::
+
+            sage: n=PerfectMatching([3,8,1,7,6,5,4,2]); n
+            PerfectMatching [(1, 3), (2, 8), (4, 7), (5, 6)]
+            sage: n.is_non_crossing()
+            False
+            sage: PerfectMatching([(1, 4), (2, 3), (5, 6)]).is_non_crossing()
+            True
+        """
+        x=self.value[:]
+        if len(x)==0:
+            return True
+        (i,j)=x.pop(0)
+        for (a,b) in x:
+            if (i<a<j<b) or (i<b<j<a) or (j<a<i<b) or (j<b<i<a) or (
+                    a<i<b<j) or (a<j<b<i) or (b<i<a<j) or (b<j<a<i):
+                return False
+        return PerfectMatching(x).is_non_crossing()
+
+    def Weingarten_function(self,other,N):
+        r"""
+        Returns the Weingarten function of two pairings. This function is the value of some integrals over the orhtogonal groups O_N.
+
+        EXAMPLES::
+
+        sage: var('N')
+        N
+        sage: m=PerfectMatching([(1,3),(2,4)])
+        sage: n=PerfectMatching([(1,2),(3,4)])
+        sage: factor(m.Weingarten_function(n,N))
+        -1/((N - 1)*(N + 2)*N)
+        """
+        W=self.parent().Weingarten_matrix(N)
+        return W[self.rank()][other.rank()]
+
+class PerfectMatchings(UniqueRepresentation,Parent):
+    r"""
+    Class of perfect matchings of a ground set. At the creation, the set can be given as any iterable object. If the argument is an integer n, it will be transformed into [1 .. n]::
+
+        sage: M=PerfectMatchings(6);M
+        Set of perfect matchings of {1, 2, 3, 4, 5, 6}
+        sage: PerfectMatchings([-1, -3, 1, 2])
+        Set of perfect matchings of {1, 2, -3, -1}
+
+    One can ask for the list, the cardinality or an element of a set of perfect matching::
+
+        sage: PerfectMatchings(4).list()
+        [PerfectMatching [(4, 1), (3, 2)], PerfectMatching [(4, 2), (3, 1)], PerfectMatching [(4, 3), (2, 1)]]
+        sage: PerfectMatchings(8).cardinality()
+        105
+        sage: M=PerfectMatchings(('a', 'e', 'b', 'f', 'c', 'd'))
+        sage: M.an_element()
+        PerfectMatching [('a', 'e'), ('c', 'd'), ('b', 'f')]
+        sage: all([PerfectMatchings(i).an_element() in PerfectMatchings(i) for i in range(2,11,2)])
+        True
+    """
+
+    @staticmethod
+    def _parse_input(objects):
+        from sage.sets.set import Set
+        r"""
+        This function tries to recognize the argument and to transform into a set. It is not meant to be called manually, but only as the first of the creation of an enumerated set of PerfectMatchings.
+        
+        EXAMPLES::
+
+            sage: PerfectMatchings._parse_input(4)
+            {1, 2, 3, 4}
+            sage: PerfectMatchings._parse_input(['a','b','c','e'])
+            {'a', 'c', 'b', 'e'}
+        """
+        #if the argument is a python integer n, we replace it by the list [1 .. n]
+        if isinstance(objects,int):
+            objects=range(1,objects+1)
+        #same thing if the argument is a sage integer.
+        elif isinstance(objects,Integer):
+            objects=range(1,objects+1)
+        #Finally, if it is iterable, we return the corresponding set. Note that it is important to return a hashable object here (in particular, NOT A LIST), see comment below.
+        if not hasattr(objects,'__iter__'):
+            raise ValueError, "do not know how to construct a set of matchings from %s (it must be iterable)"
+        return Set(objects)
+
+    @staticmethod
+    def __classcall__(cls, objects):
+        r"""
+        This function is called automatically when the user want to create an enumerated set of PerfectMatchings.
+
+        EXAMPLES::
+
+            sage: M=PerfectMatchings(6);M
+            Set of perfect matchings of {1, 2, 3, 4, 5, 6}
+            sage: PerfectMatchings([-1, -3, 1, 2])
+            Set of perfect matchings of {1, 2, -3, -1}
+
+        If one has already created a set of perfect matchings of the same set, it does not create a new object, but returns the already existing one::
+
+            sage: N=PerfectMatchings((2, 3, 5, 4, 1, 6))
+            sage: N is M
+            True
+
+        The class constructor does not check that the perfect matching is correct, one has to use the function __contains__ for that::
+
+            sage: m=PerfectMatching([(1,2,3),(4,5)])
+            sage: isinstance(m,PerfectMatching)
+            True
+            sage: m in m.parent()
+            False
+
+        TEST::
+
+            sage: TestSuite(M).run()
+        """
+        #we call the constructor of an other class, which will
+        #    - check if the object has already been constructed (so the second argument, i.e. the output of _parse_input, must be hashable)
+        #    - look for a place in memory and call the __init__ function
+        return super(PerfectMatchings, cls).__classcall__(
+                         cls, cls._parse_input(objects))
+
+    def __init__(self,objects):
+        r"""
+        See __classcall__?
+        """
+        self._objects=objects
+        Parent.__init__(self, category = FiniteEnumeratedSets())
+
+    def _repr_(self):
+        r"""
+        Returns a description of `self`
+
+        EXAMPLES::
+       
+            sage: PerfectMatchings([-1, -3, 1, 2])
+            Set of perfect matchings of {1, 2, -3, -1}
+        """
+        return "Set of perfect matchings of %s"%self._objects
+
+    def __iter__(self):
+        r"""
+        Returns an iterator for the elements of self
+
+        EXAMPLES::
+
+            sage: PerfectMatchings(4).list()
+            [PerfectMatching [(4, 1), (3, 2)], PerfectMatching [(4, 2), (3, 1)], PerfectMatching [(4, 3), (2, 1)]]
+        """
+        if len(self._objects) == 0:
+            yield self([])
+        elif len(self._objects) == 1:
+            pass
+        else: 
+            l=list(self._objects)
+            a=l.pop(-1)
+            for i in range(len(l)):
+                obj_rest=l[:]
+                b=obj_rest.pop(i)
+                for p in PerfectMatchings(obj_rest):
+                    yield self([(a,b)]+p.value)
+
+
+    def __contains__(self,x):
+        from sage.misc.flatten import flatten
+        from sage.combinat.permutation import Permutations
+        r"""
+        Tests if x is an element of self.
+
+        EXAMPLES::
+
+            sage: m=PerfectMatching([(1,2),(4,3)])
+            sage: m in PerfectMatchings(4)
+            True
+            sage: m in PerfectMatchings((0, 1, 2, 3))
+            False
+            sage: all([m in PerfectMatchings(6) for m in PerfectMatchings(6)])
+            True
+
+        Note that the class of x does not need to be PerfectMatching: if the data defines a perfect matching of the good set, the function returns True::
+
+            sage: [(1, 4), (2, 3)] in PerfectMatchings(4)
+            True
+
+        The class constructor does not check that the perfect matching is correct, one has to use the function __contains__ for that::
+
+            sage: m=PerfectMatching([(1,2,3),(4,5)])
+            sage: isinstance(m,PerfectMatching)
+            True
+            sage: m in m.parent()
+            False
+        """
+        if not isinstance(x,PerfectMatching):
+            try:
+                x=PerfectMatching(x)
+            except ValueError:
+                return False
+        if x.parent() is not self:
+            return False
+        A2N=dict([(self._objects[i],i+1) for i in range(len(self._objects))])
+        if not all([len(i)==2 for i in x.value]):
+            return False
+        if map(lambda a:A2N[a],flatten(x.value)) not in Permutations(x.size()):
+            return False
+        return True
+  
+    def cardinality(self):
+        from sage.misc.misc_c import prod
+        r"""
+        Returns the cardinality of the set of perfect matching `self`, that is 1*3*5*...*(2n-1), where 2n is the size of the ground set.
+
+        EXAMPLES::
+
+            sage: PerfectMatchings(8).cardinality()
+            105
+        """
+        n=len(self._objects)
+        if n%2==1:
+            return 0
+        else:
+            return prod(i for i in range(n) if i%2==1)
+
+    def an_element(self):
+        r"""
+        Returns an element of self.
+
+        EXAMPLES::
+
+            sage: M=PerfectMatchings(('a', 'e', 'b', 'f', 'c', 'd'))
+            sage: M.an_element()
+            PerfectMatching [('a', 'e'), ('c', 'd'), ('b', 'f')]
+            sage: all([PerfectMatchings(i).an_element() in PerfectMatchings(i) for i in range(2,11,2)])
+            True
+        """
+        n=len(self._objects)//2
+        return PerfectMatching([(self._objects[i],self._objects[i+n]) for i in range(n)])
+
+    @cached_method
+    def Weingarten_matrix(self,N):
+        from sage.matrix.constructor import Matrix
+        r"""
+        Returns the Weingarten matrix corresponding to the set of PerfectMatchings `self`. It is a useful theoretical tool to compute polynomial integral over the orthogonal group O_N.
+
+        EXAMPLES::
+
+            sage: M=PerfectMatchings(4).Weingarten_matrix(var('N'))
+            sage: N*(N-1)*(N+2)*M.apply_map(factor)
+            [N + 1    -1    -1]
+            [   -1 N + 1    -1]
+            [   -1    -1 N + 1]
+        """
+        G=Matrix([ [N**(p1.number_of_loops(p2)) for p1 in self]
+            for p2 in self])
+        return G**(-1)
+
+    Element=PerfectMatching
+