passagemath-combinat 10.6.1__cp312-cp312-musllinux_1_2_aarch64.whl → 10.8.1a1__cp312-cp312-musllinux_1_2_aarch64.whl

sage/combinat/degree_sequences.pyx

@@ -13,26 +13,26 @@ With the object ``DegreeSequences(n)``, one can:
 * Check whether a sequence is indeed a degree sequence::
 
     sage: DS = DegreeSequences(5)
-    sage: [4, 3, 3, 3, 3] in DS
+    sage: (4, 3, 3, 3, 3) in DS
     True
-    sage: [4, 4, 0, 0, 0] in DS
+    sage: (4, 4, 0, 0, 0) in DS
     False
 
 * List all the possible degree sequences of length `n`::
 
     sage: for seq in DegreeSequences(4):
     ....:     print(seq)
-    [0, 0, 0, 0]
-    [1, 1, 0, 0]
-    [2, 1, 1, 0]
-    [3, 1, 1, 1]
-    [1, 1, 1, 1]
-    [2, 2, 1, 1]
-    [2, 2, 2, 0]
-    [3, 2, 2, 1]
-    [2, 2, 2, 2]
-    [3, 3, 2, 2]
-    [3, 3, 3, 3]
+    (0, 0, 0, 0)
+    (1, 1, 0, 0)
+    (2, 1, 1, 0)
+    (3, 1, 1, 1)
+    (1, 1, 1, 1)
+    (2, 2, 1, 1)
+    (2, 2, 2, 0)
+    (3, 2, 2, 1)
+    (2, 2, 2, 2)
+    (3, 3, 2, 2)
+    (3, 3, 3, 3)
 
 .. NOTE::
 
@@ -40,7 +40,7 @@ With the object ``DegreeSequences(n)``, one can:
     :func:`~sage.graphs.generators.degree_sequence.DegreeSequence`.
     For instance::
 
-        sage: ds = [3, 3, 2, 2, 2, 2, 2, 1, 1, 0]
+        sage: ds = (3, 3, 2, 2, 2, 2, 2, 1, 1, 0)
         sage: g = graphs.DegreeSequence(ds)                                             # needs networkx sage.graphs
         sage: g.degree_sequence()                                                       # needs networkx sage.graphs
         [3, 3, 2, 2, 2, 2, 2, 1, 1, 0]
@@ -196,7 +196,8 @@ Indeed, when enumerating all the degree sequences of length `n`, Sage first
 allocates an array ``seq`` of `n+1` integers where ``seq[i]`` is the number of
 elements of value ``i`` in the current sequence. Obviously, ``seq[n]=0`` holds
 in permanence : it is useful to allocate a larger array than necessary to
-simplify the code. The ``seq`` array is a global variable.
+simplify the code. The ``seq`` array lives inside a short-lived enumerator
+object created for each traversal so that no global state leaks between calls.
 
 The recursive function ``enum(depth, maximum)`` is the one building the list of
 sequences. It builds the list of degree sequences of length `n` which *extend*
@@ -254,15 +255,6 @@ Checking the consistency of enumeration and test::
     sage: DS = DegreeSequences(6)
     sage: all(seq in DS for seq in DS)
     True
-
-.. WARNING::
-
-    For the moment, iterating over all degree sequences involves building the
-    list of them first, then iterate on this list.  This is obviously bad,
-    as it requires uselessly a **lot** of memory for large values of `n`.
-
-    This should be changed. Updating the code does not require more
-    than a couple of minutes.
 """
 
 # ****************************************************************************
@@ -276,11 +268,7 @@ Checking the consistency of enumeration and test::
 # ****************************************************************************
 
 from cysignals.memory cimport check_calloc, sig_free
-from cysignals.signals cimport sig_on, sig_off
-
-
-cdef unsigned char * seq
-cdef list sequences
+from sage.rings.integer import Integer
 
 
 class DegreeSequences:
@@ -299,20 +287,32 @@ class DegreeSequences:
 
             sage: DegreeSequences(8)
             Degree sequences on 8 elements
-            sage: [3,3,2,2,2,2,2,2] in DegreeSequences(8)
+            sage: DegreeSequences(1)
+            Degree sequences on 1 element
+            sage: (3,3,2,2,2,2,2,2) in DegreeSequences(8)
             True
 
         TESTS:
 
         :issue:`21824`::
 
+            sage: DegreeSequences(RR(1/2))
+            Traceback (most recent call last):
+            ...
+            TypeError: the input parameter must be a non-negative integer
             sage: DegreeSequences(-1)
             Traceback (most recent call last):
             ...
             ValueError: the input parameter must be >= 0
         """
+        try:
+            n = Integer(n)
+        except (TypeError, ValueError):
+            raise TypeError("the input parameter must be a non-negative integer")
+
         if n < 0:
             raise ValueError("the input parameter must be >= 0")
+
         self._n = n
 
     def __contains__(self, seq):
@@ -322,26 +322,33 @@ class DegreeSequences:
 
         EXAMPLES::
 
-            sage: [3,3,2,2,2,2,2,2] in DegreeSequences(8)
+            sage: (3,3,2,2,2,2,2,2) in DegreeSequences(8)
             True
 
         TESTS:
 
         :issue:`15503`::
 
-            sage: [2,2,2,2,1,1,1] in DegreeSequences(7)
+            sage: (2,2,2,2,1,1,1) in DegreeSequences(7)
             False
 
         :issue:`21824`::
 
             sage: [d for d in DegreeSequences(0)]
-            [[]]
+            [()]
             sage: [d for d in DegreeSequences(1)]
-            [[0]]
+            [(0,)]
             sage: [d for d in DegreeSequences(3)]
-            [[0, 0, 0], [1, 1, 0], [2, 1, 1], [2, 2, 2]]
+            [(0, 0, 0), (1, 1, 0), (2, 1, 1), (2, 2, 2)]
             sage: [d for d in DegreeSequences(1)]
-            [[0]]
+            [(0,)]
+
+        For lists we can also check containment::
+
+            sage: [3,3,2,2,2,2,2,2] in DegreeSequences(8)
+            True
+            sage: [2,2,2,2,1,1,1] in DegreeSequences(7)
+            False
         """
         cdef int n = self._n
         if len(seq) != n:
@@ -391,15 +398,14 @@ class DegreeSequences:
             sage: DegreeSequences(6)
             Degree sequences on 6 elements
         """
+        if self._n == 1:
+            return "Degree sequences on 1 element"
         return "Degree sequences on "+str(self._n)+" elements"
 
     def __iter__(self):
         """
         Iterate over all the degree sequences.
 
-        TODO: THIS SHOULD BE UPDATED AS SOON AS THE YIELD KEYWORD APPEARS IN
-        CYTHON. See comment in the class' documentation.
-
         EXAMPLES::
 
             sage: DS = DegreeSequences(6)
@@ -408,181 +414,228 @@ class DegreeSequences:
         """
         yield from init(self._n)
 
-    def __dealloc__():
-        """
-        Freeing the memory
-        """
-        sig_free(seq)
-
-
-cdef init(int n):
+cdef class _DegreeSequenceEnumerator:
     """
-    Initialize the memory and starts the enumeration algorithm.
+    Internal enumerator class for degree sequences.
+
+    This class manages the memory and state for enumerating all degree
+    sequences of a given length using the algorithm described in [RCES1994]_.
+
+    EXAMPLES::
+
+        sage: from sage.combinat.degree_sequences import _DegreeSequenceEnumerator
+        sage: e = _DegreeSequenceEnumerator(4)
+        sage: list(e.enum(1, 0))
+        [(0, 0, 0, 0),
+         (1, 1, 0, 0),
+         (2, 1, 1, 0),
+         (3, 1, 1, 1),
+         (1, 1, 1, 1),
+         (2, 2, 1, 1),
+         (2, 2, 2, 0),
+         (3, 2, 2, 1),
+         (2, 2, 2, 2),
+         (3, 3, 2, 2),
+         (3, 3, 3, 3)]
     """
-    global seq
-    global N
-    global sequences
+    cdef int N
+    cdef unsigned char * seq
 
-    if n == 0:
-        return [[]]
-    elif n == 1:
-        return [[0]]
+    def __cinit__(self, int n):
+        """
+        Allocate memory for the degree sequence enumerator.
 
-    seq = <unsigned char *>check_calloc(n + 1, sizeof(unsigned char))
+        This method allocates an array of `n+1` unsigned chars to store
+        the count of vertices at each degree level. The array is
+        zero-initialized, and ``seq[0]`` is set to 1 to represent the
+        initial state with one vertex of degree 0.
 
-    # We begin with one vertex of degree 0
-    seq[0] = 1
+        INPUT:
 
-    N = n
-    sequences = []
-    enum(1, 0)
-    sig_free(seq)
-    return sequences
+        - ``n`` -- positive integer; the number of vertices
 
-cdef inline add_seq():
-    """
-    This function is called whenever a sequence is found.
+        TESTS::
 
-    Build the degree sequence corresponding to the current state of the
-    algorithm and adds it to the sequences list.
-    """
-    global sequences
-    global N
-    global seq
+            sage: from sage.combinat.degree_sequences import _DegreeSequenceEnumerator
+            sage: e = _DegreeSequenceEnumerator(2)
+        """
+        self.seq = NULL
+        self.N = n
+        self.seq = <unsigned char *>check_calloc(n + 1, sizeof(unsigned char))
+        self.seq[0] = 1
 
-    cdef list s = []
-    cdef int i, j
+    def __dealloc__(self):
+        """
+        Deallocate the memory used by the enumerator.
 
-    for N > i >= 0:
-        for 0 <= j < seq[i]:
-            s.append(i)
+        This method frees the memory allocated for the ``seq`` array
+        when the enumerator object is garbage collected.
 
-    sequences.append(s)
+        TESTS::
 
+            sage: from sage.combinat.degree_sequences import _DegreeSequenceEnumerator
+            sage: e = _DegreeSequenceEnumerator(3)
+            sage: del e
+        """
+        if self.seq != NULL:
+            sig_free(self.seq)
+            self.seq = NULL
 
-cdef void enum(int k, int M) noexcept:
-    r"""
-    Main function; for an explanation of the algorithm please refer to the
-    :mod:`sage.combinat.degree_sequences` documentation.
+    cdef tuple build_current_seq(self):
+        """
+        Return the degree sequence represented by the current counts.
+        """
+        cdef list s = []
+        cdef int i, j
+        cdef int count
 
-    INPUT:
+        for i in range(self.N - 1, -1, -1):
+            count = self.seq[i]
+            for j in range(count):
+                s.append(i)
 
-    - ``k`` -- depth of the partial degree sequence
-    - ``M`` -- value of a maximum element in the partial degree sequence
-    """
-    cdef int i, j
-    global seq
-    cdef int taken = 0
-    cdef int current_box
-    cdef int n_current_box
-    cdef int n_previous_box
-    cdef int new_vertex
-
-    # Have we found a new degree sequence ? End of recursion !
-    if k == N:
-        add_seq()
-        return
+        return tuple(s)
 
-    sig_on()
+    def enum(self, int k, int M):
+        r"""
+        Main function; for an explanation of the algorithm please refer to the
+        :mod:`sage.combinat.degree_sequences` documentation.
 
-    #############################################
-    # Creating vertices of Vertices of degree M #
-    #############################################
+        INPUT:
 
-    # If 0 is the current maximum degree, we can always extend the degree
-    # sequence with another 0
-    if M == 0:
+        - ``k`` -- depth of the partial degree sequence
+        - ``M`` -- value of a maximum element in the partial degree sequence
 
-        seq[0] += 1
-        enum(k + 1, M)
-        seq[0] -= 1
+        This is a generator that yields degree sequences.
+        """
+        cdef int i, j
+        cdef unsigned char * seq = self.seq
+        cdef int N = self.N
+        cdef int taken = 0
+        cdef int current_box
+        cdef int n_current_box
+        cdef int n_previous_box
+        cdef int new_vertex
+
+        # Have we found a new degree sequence ? End of recursion !
+        if k == N:
+            yield self.build_current_seq()
+            return
+
+        ####################################
+        # Creating vertices of degree M #
+        ####################################
+
+        # If 0 is the current maximum degree, we can always extend the degree
+        # sequence with another 0
+        if M == 0:
+
+            seq[0] += 1
+            yield from self.enum(k + 1, M)
+            seq[0] -= 1
+
+        # We need not automatically increase the degree at each step. In this case,
+        # we have no other choice but to link the new vertex of degree M to vertices
+        # of degree M-1, which will become vertices of degree M too.
+        elif seq[M - 1] >= M:
+
+            seq[M] += M + 1
+            seq[M - 1] -= M
+
+            yield from self.enum(k + 1, M)
+
+            seq[M] -= M + 1
+            seq[M - 1] += M
+
+        ######################################
+        # Creating vertices of degree > M #
+        ######################################
+
+        for current_box in range(M, 0, -1):
+
+            # If there is not enough vertices in the boxes available
+            if taken + (seq[current_box] - 1) + seq[current_box-1] <= M:
+                taken += seq[current_box]
+                seq[current_box+1] += seq[current_box]
+                seq[current_box] = 0
+                continue
+
+            # The degree of the new vertex will be taken + i + j where:
+            #
+            # * i is the number of vertices taken in the *current* box
+            # * j the number of vertices taken in the *previous* one
+
+            n_current_box = seq[current_box]
+            n_previous_box = seq[current_box-1]
+
+            # Note to self, and others:
+            #
+            # In the following lines, there are many incrementation/decrementation
+            # that *may* be replaced by only +1 and -1 and save some
+            # instructions. This would involve adding several "if", and I feared it
+            # would make the code even uglier. If you are willing to give it a try,
+            # **please check the results** ! It is trickier that it seems ! Even
+            # changing the lower bounds in the for loops would require tests
+            # afterwards.
+
+            for i in range(max(0, (M + 1) - n_previous_box - taken), n_current_box):
+                seq[current_box] -= i
+                seq[current_box+1] += i
+
+                for j in range(max(0, (M + 1) - taken - i), n_previous_box + 1):
+                    seq[current_box-1] -= j
+                    seq[current_box] += j
+
+                    new_vertex = taken + i + j
+                    seq[new_vertex] += 1
+                    yield from self.enum(k+1, new_vertex)
+                    seq[new_vertex] -= 1
+
+                    seq[current_box-1] += j
+                    seq[current_box] -= j
+
+                seq[current_box] += i
+                seq[current_box+1] -= i
+
+            taken += n_current_box
+            seq[current_box] = 0
+            seq[current_box+1] += n_current_box
 
-    # We need not automatically increase the degree at each step. In this case,
-    # we have no other choice but to link the new vertex of degree M to vertices
-    # of degree M-1, which will become vertices of degree M too.
-    elif seq[M - 1] >= M:
+        # Corner case
+        #
+        # Now current_box = 0. All the vertices of nonzero degree are taken, we just
+        # want to know how many vertices of degree 0 will be neighbors of the new
+        # vertex.
+        for i in range(max(0, (M + 1) - taken), seq[0] + 1):
 
-        seq[M] += M + 1
-        seq[M - 1] -= M
+            seq[1] += i
+            seq[0] -= i
+            seq[taken+i] += 1
 
-        enum(k + 1, M)
+            yield from self.enum(k+1, taken+i)
 
-        seq[M] -= M + 1
-        seq[M - 1] += M
+            seq[taken+i] -= 1
+            seq[1] -= i
+            seq[0] += i
 
-    ###############################################
-    # Creating vertices of Vertices of degree > M #
-    ###############################################
+        # Shift everything back to normal ! ( cell N is always equal to 0)
+        for i in range(1, N):
+            seq[i] = seq[i+1]
 
-    for M >= current_box > 0:
 
-        # If there is not enough vertices in the boxes available
-        if taken + (seq[current_box] - 1) + seq[current_box-1] <= M:
-            taken += seq[current_box]
-            seq[current_box+1] += seq[current_box]
-            seq[current_box] = 0
-            continue
+def init(int n):
+    """
+    Initialize the memory and starts the enumeration algorithm.
 
-        # The degree of the new vertex will be taken + i + j where:
-        #
-        # * i is the number of vertices taken in the *current* box
-        # * j the number of vertices taken in the *previous* one
+    This is a generator that yields degree sequences one at a time.
+    """
+    if n == 0:
+        yield ()
+        return
+    elif n == 1:
+        yield (0,)
+        return
 
-        n_current_box = seq[current_box]
-        n_previous_box = seq[current_box-1]
+    cdef _DegreeSequenceEnumerator enumerator = _DegreeSequenceEnumerator(n)
 
-        # Note to self, and others:
-        #
-        # In the following lines, there are many incrementation/decrementation
-        # that *may* be replaced by only +1 and -1 and save some
-        # instructions. This would involve adding several "if", and I feared it
-        # would make the code even uglier. If you are willing to give it a try,
-        # **please check the results** ! It is trickier that it seems ! Even
-        # changing the lower bounds in the for loops would require tests
-        # afterwards.
-
-        for max(0, (M+1)-n_previous_box-taken) <= i < n_current_box:
-            seq[current_box] -= i
-            seq[current_box+1] += i
-
-            for max(0, ((M+1)-taken-i)) <= j <= n_previous_box:
-                seq[current_box-1] -= j
-                seq[current_box] += j
-
-                new_vertex = taken + i + j
-                seq[new_vertex] += 1
-                enum(k+1, new_vertex)
-                seq[new_vertex] -= 1
-
-                seq[current_box-1] += j
-                seq[current_box] -= j
-
-            seq[current_box] += i
-            seq[current_box+1] -= i
-
-        taken += n_current_box
-        seq[current_box] = 0
-        seq[current_box+1] += n_current_box
-
-    # Corner case
-    #
-    # Now current_box = 0. All the vertices of nonzero degree are taken, we just
-    # want to know how many vertices of degree 0 will be neighbors of the new
-    # vertex.
-    for max(0, ((M+1)-taken)) <= i <= seq[0]:
-
-        seq[1] += i
-        seq[0] -= i
-        seq[taken+i] += 1
-
-        enum(k+1, taken+i)
-
-        seq[taken+i] -= 1
-        seq[1] -= i
-        seq[0] += i
-
-    # Shift everything back to normal ! ( cell N is always equal to 0)
-    for 1 <= i < N:
-        seq[i] = seq[i+1]
-
-    sig_off()
+    yield from enumerator.enum(1, 0)

sage/combinat/derangements.py

@@ -349,9 +349,9 @@ class Derangements(UniqueRepresentation, Parent):
             sage: D._fixed_point([5,4,3,2,1])
             True
         """
-        return any(x == y for (x, y) in zip(a, self._set))
+        return any(x == y for x, y in zip(a, self._set))
 
-    def _count_der(self, n):
+    def _count_der(self, n) -> Integer:
         """
         Count the number of derangements of `n` using the recursion
         `D_2 = 1, D_3 = 2, D_n = (n-1) (D_{n-1} + D_{n-2})`.
@@ -385,8 +385,10 @@ class Derangements(UniqueRepresentation, Parent):
 
     def cardinality(self):
         r"""
-        Counts the number of derangements of a positive integer, a
-        list, or a string.  The list or string may contain repeated
+        Count the number of derangements of a positive integer, a list,
+        or a string.
+
+        The list or string may contain repeated
         elements.  If an integer `n` is given, the value returned
         is the number of derangements of `[1, 2, 3, \ldots, n]`.
 
@@ -433,17 +435,16 @@ class Derangements(UniqueRepresentation, Parent):
             A = [self._set.count(i) for i in sL]
             R = PolynomialRing(QQ, 'x', len(A))
             S = sum(R.gens())
-            e = prod((S - x)**y for (x, y) in zip(R.gens(), A))
+            e = prod((S - x)**y for x, y in zip(R.gens(), A))
             return Integer(e.coefficient(dict(zip(R.gens(), A))))
         return self._count_der(len(self._set))
 
     def _rand_der(self):
         r"""
-        Produces a random derangement of `[1, 2, \ldots, n]`.
+        Return a random derangement of `[1, 2, \ldots, n]`.
 
-        This is an
-        implementation of the algorithm described by Martinez et. al. in
-        [MPP2008]_.
+        This is an implementation of the algorithm described by
+        Martinez et. al. in [MPP2008]_.
 
         EXAMPLES::
 
@@ -464,7 +465,7 @@ class Derangements(UniqueRepresentation, Parent):
                         A[i - 1], A[j - 1] = A[j - 1], A[i - 1]
                         break
                 p = random()
-                if p < (u - 1) * self._count_der(u - 2) // self._count_der(u):
+                if p * self._count_der(u) < (u - 1) * self._count_der(u - 2):
                     mark[j - 1] = True
                     u -= 1
                 u -= 1
@@ -472,22 +473,17 @@ class Derangements(UniqueRepresentation, Parent):
         return A
 
     def random_element(self):
-        r"""
-        Produce all derangements of a positive integer, a list, or
-        a string.  The list or string may contain repeated elements.
-        If an integer `n` is given, then a random
-        derangements of `[1, 2, 3, \ldots, n]` is returned
+        r"""Return a random derangement.
 
-        For an integer, or a list or string with all elements
-        distinct, the value is obtained by an algorithm described in
-        [MPP2008]_. For a list or string with repeated elements the
-        derangement is formed by choosing an element at random from the list of
-        all possible derangements.
+        If the elements of the underlying multiset are all distinct,
+        an algorithm described in [MPP2008]_ is used.  For a list or
+        string with repeated elements the derangement is formed by
+        choosing an element at random from the list of all possible
+        derangements.
 
         OUTPUT:
 
-        A single list or string containing a derangement, or an
-        empty list if there are no derangements.
+        A derangement, or an empty list if there are no derangements.
 
         EXAMPLES::
 
@@ -516,6 +512,13 @@ class Derangements(UniqueRepresentation, Parent):
 
             sage: D = Derangements([1,1,2,2])
             sage: _ = [D.random_element() for _ in range(20)]
+
+        Check that we do not produce a derangement of a single
+        element::
+
+            sage: D = Derangements(1)
+            sage: D.random_element()
+            []
         """
         if self.__multi:
             L = list(self)
@@ -523,5 +526,8 @@ class Derangements(UniqueRepresentation, Parent):
                 return self.element_class(self, [])
             i = randrange(len(L))
             return L[i]
+
+        if len(self._set) == 1:
+            return self.element_class(self, [])
         temp = self._rand_der()
         return self.element_class(self, [self._set[ii - 1] for ii in temp])