passagemath-combinat 10.6.42__cp314-cp314-musllinux_1_2_x86_64.whl

sage/games/sudoku_backtrack.pyx

@@ -0,0 +1,189 @@
+# sage_setup: distribution = sagemath-combinat
+r"""
+This module contains Cython code for a backtracking algorithm to solve Sudoku puzzles.
+
+Once Cython implements closures and the ``yield`` keyword is possible, this can be moved into the ``sage.games.sudoku`` module, as part of the ``Sudoku.backtrack`` method, and this module can be banned.
+"""
+
+
+def backtrack_all(n, puzzle):
+    r"""
+    A routine to compute all the solutions to a Sudoku puzzle.
+
+    INPUT:
+
+        - ``n`` -- the size of the puzzle, where the array is an `n^2\times n^2` grid
+
+        - ``puzzle`` -- list of the entries of the puzzle (1-based), in row-major order
+
+    OUTPUT:
+
+        A list of solutions, where each solution is a (1-based) list similar to ``puzzle``.
+
+    TESTS:
+
+    This is just a cursory test here, since eventually this code will move.
+    See the `backtrack` method of the `Sudoku` class in the
+    `sage.games.sudoku` module for more enlightening examples. ::
+
+        sage: from sage.games.sudoku_backtrack import backtrack_all
+        sage: c = [0, 0, 0, 0, 1, 0, 9, 0, 0, 8, 0, 0, 4, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 7, 0, 0, 3, 0, 0, 0,0, 0, 0, 0, 0, 0, 0, 2, 0, 4, 0, 0, 0, 0, 0, 0, 0, 5, 8, 0, 6, 0, 0, 0, 0, 1, 3, 0, 7, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 8, 0, 0, 0, 0, 0]
+        sage: print(backtrack_all(3, c))
+        [[6, 5, 4, 3, 1, 2, 9, 8, 7, 8, 3, 1, 4, 7, 9, 5, 2, 6, 2, 9, 7, 6, 8, 5, 4, 1, 3, 4, 7, 2, 5, 3, 8, 6, 9, 1, 3, 8, 5, 1, 9, 6, 2, 7, 4, 9, 1, 6, 7, 2, 4, 3, 5, 8, 5, 6, 8, 9, 4, 7, 1, 3, 2, 7, 4, 3, 2, 5, 1, 8, 6, 9, 1, 2, 9, 8, 6, 3, 7, 4, 5]]
+
+    ALGORITHM:
+
+    We traverse a search tree depth-first.  Each level of the tree corresponds to a location in the grid, listed in row-major order.  At each location we maintain a list of the symbols which may be used in that location as follows.
+
+    A location has "peers", which are the locations in the same row, column or box (sub-grid).  As symbols are chosen (or fixed initially) at a location, they become ineligible for use at a peer.  We track this in the ``available`` array where at each location each symbol has a count of how many times it has been made ineligible.  As this counter transitions between 0 and 1, the number of eligible symbols at a location is tracked in the ``card`` array.  When the number of eligible symbols at any location becomes 1, then we know that *must* be the symbol employed in that location.  This then allows us to further update the eligible symbols at the peers of that location.  When the number of the eligible symbols at any location becomes 0, then we know that we can prune the search tree.
+
+    So at each new level of the search tree, we propagate as many fixed symbols as we can, placing them into a two-ended queue (``fixed`` and ``fixed_symbol``) that we process until it is empty or we need to prune.  All this recording of ineligible symbols and numbers of eligible symbols has to be unwound as we backup the tree, though.
+
+    The notion of propagating singleton cells forward comes from an essay by Peter Norvig [sudoku:norvig]_.
+    """
+    cdef:
+        # Arrays sizes are n^4, and n^2, with 3n^2-2n-1 for second slot of peers, n = 4
+        int i, j, count, level, apeer
+        int nsquare, npeers, nboxes
+        int grid_row, grid_col, grid_corner
+        int peers[256][39]
+        int box[256]
+        int available[256][16]
+        int card[256]
+        int hint, symbol, abox
+        int feasible
+        int nfixed[256]
+        int fixed[256][256]
+        int fixed_symbol[256][256]
+
+        int process, asymbol, alevel, process_level, process_symbol
+
+    # sanity check on size (types)
+    # n is "base" dimension
+    # nsquare is size of a grid
+    # nboxes is total number of entries
+    nsquare = n*n
+    nboxes = nsquare * nsquare
+    npeers = 3*n*n-2*n-1  # 2(n^2-1)+n^2-2n+1
+
+    # "Peers" of a box are boxes in the same column, row or grid
+    # Like the conflict graph when expressed as a graph coloring problem
+    for level in range(nboxes):
+        # location as row and column in square
+        # grids are numbered similarly, in row-major order
+        row = level // nsquare
+        col = level % nsquare
+        grid_corner = (row - (row % n))*nsquare + (col - (col % n))
+        grid_row = row // n
+        grid_col = col // n
+        count = -1
+        # Peers' levels in same grid, but not the box itself
+        for i in range(n):
+            for j in range(n):
+                grid_level = grid_corner + i*nsquare + j
+                if grid_level != level:
+                    count += 1
+                    peers[level][count] = grid_level
+        # Peers' levels in the same row, but not in grid
+        for i in range(nsquare):
+            if (i // 3 != grid_col):
+                count += 1
+                peers[level][count] = row*nsquare + i
+        # Peers' levels in same column, but not in grid
+        for i in range(nsquare):
+            if (i // 3 != grid_row):
+                count += 1
+                peers[level][count] = col + i*nsquare
+
+    # Initialize data structures
+    # Make every symbol available initially for a box
+    # And make set cardinality the size of symbol set
+    for level in range(nboxes):
+        box[level] = -1
+        card[level] = nsquare
+        for j in range(nsquare):
+            available[level][j] = 0
+
+    # For nonzero entries of input puzzle
+    # (1) Convert to zero-based indexing
+    # (2) Make a set of size 1 available initially
+    for level in range(nboxes):
+        # location as row and column in square
+        # grids are numbered similarly, in row-major order
+        hint = puzzle[level] - 1
+        if hint != -1:
+            # Limit symbol set at the hint's location to a singleton
+            for j in range(nsquare):
+                available[level][j] = 1
+            available[level][hint] = 0
+            card[level] = 1
+            #  Remove hint from all peers' available symbols
+            #  Track cardinality as sets adjust
+            for i in range(npeers):
+                apeer = peers[level][i]
+                available[apeer][hint] += 1
+                if available[apeer][hint] == 1:
+                    card[apeer] -= 1
+
+    # Start backtracking
+    solutions = []
+    level = 0
+    box[level] = -1
+    while (level > -1):
+        symbol = box[level]
+        if (symbol != -1):
+            # restore symbols to peers
+            for i in range(nfixed[level]):
+                alevel = fixed[level][i]
+                asymbol = fixed_symbol[level][i]
+                for j in range(npeers):
+                    abox = peers[alevel][j]
+                    available[abox][asymbol] -= 1
+                    if available[abox][asymbol] == 0:
+                        card[abox] += 1
+        # move sideways in search tree to next available symbol
+        symbol += 1
+        while (symbol < nsquare) and (available[level][symbol] != 0):
+            symbol += 1
+        if symbol == nsquare:
+            # fell off the end sideways, backup
+            level = level - 1
+        else:
+            box[level] = symbol
+            # Remove elements of sets, adjust cardinalities
+            # Descend in search tree if no empty sets created
+            # Can't break early at an empty set
+            #   or we will confuse restore that happens immediately
+            feasible = True
+            fixed[level][0] = level
+            fixed_symbol[level][0] = symbol
+            count = 0
+            process = -1
+            while (process < count) and feasible:
+                process += 1
+                process_level = fixed[level][process]
+                process_symbol = fixed_symbol[level][process]
+                for i in range(npeers):
+                    abox = peers[process_level][i]
+                    available[abox][process_symbol] += 1
+                    if available[abox][process_symbol] == 1:
+                        card[abox] -= 1
+                        if card[abox] == 0:
+                            feasible = False
+                        if card[abox] == 1:
+                            count += 1
+                            fixed[level][count] = abox
+                            asymbol = 0
+                            while (available[abox][asymbol] != 0):
+                                asymbol += 1
+                            fixed_symbol[level][count] = asymbol
+            nfixed[level] = process+1
+            if feasible:
+                if level == nboxes - 1:
+                    # Have a solution to save, stay at this bottom-most level
+                    # Once Cython implements closures, a yield can go here
+                    solutions.append([box[i]+1 for i in range(nboxes)])
+                else:
+                    level = level + 1
+                    box[level] = -1
+    return solutions

sage/groups/all__sagemath_combinat.py

@@ -0,0 +1 @@
+# sage_setup: distribution = sagemath-combinat

sage/groups/indexed_free_group.py

@@ -0,0 +1,489 @@
+# sage_setup: distribution = sagemath-combinat
+# sage.doctest: needs sage.combinat
+"""
+Indexed Free Groups
+
+Free groups and free abelian groups implemented using an indexed set of
+generators.
+
+AUTHORS:
+
+- Travis Scrimshaw (2013-10-16): Initial version
+"""
+
+##############################################################################
+#       Copyright (C) 2013 Travis Scrimshaw <tscrim at ucdavis.edu>
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#
+#  The full text of the GPL is available at:
+#
+#                  https://www.gnu.org/licenses/
+##############################################################################
+
+from sage.categories.groups import Groups
+from sage.categories.poor_man_map import PoorManMap
+from sage.groups.group import Group, AbelianGroup
+from sage.monoids.indexed_free_monoid import (IndexedMonoid,
+                                              IndexedFreeMonoidElement,
+                                              IndexedFreeAbelianMonoidElement)
+from sage.misc.cachefunc import cached_method
+import sage.data_structures.blas_dict as blas
+from sage.rings.integer import Integer
+from sage.rings.infinity import infinity
+from sage.sets.family import Family
+
+
+class IndexedGroup(IndexedMonoid):
+    """
+    Base class for free (abelian) groups whose generators are indexed
+    by a set.
+
+    TESTS:
+
+    We check finite properties::
+
+        sage: G = Groups().free(index_set=ZZ)
+        sage: G.is_finite()
+        False
+        sage: G = Groups().free(index_set='abc')
+        sage: G.is_finite()
+        False
+        sage: G = Groups().free(index_set=[])
+        sage: G.is_finite()
+        True
+
+    ::
+
+        sage: G = Groups().Commutative().free(index_set=ZZ)
+        sage: G.is_finite()
+        False
+        sage: G = Groups().Commutative().free(index_set='abc')
+        sage: G.is_finite()
+        False
+        sage: G = Groups().Commutative().free(index_set=[])
+        sage: G.is_finite()
+        True
+    """
+    def order(self):
+        r"""
+        Return the number of elements of ``self``, which is `\infty` unless
+        this is the trivial group.
+
+        EXAMPLES::
+
+            sage: G = Groups().free(index_set=ZZ)
+            sage: G.order()
+            +Infinity
+            sage: G = Groups().Commutative().free(index_set='abc')
+            sage: G.order()
+            +Infinity
+            sage: G = Groups().Commutative().free(index_set=[])
+            sage: G.order()
+            1
+        """
+        return self.cardinality()
+
+    def rank(self):
+        """
+        Return the rank of ``self``.
+
+        This is the number of generators of ``self``.
+
+        EXAMPLES::
+
+            sage: G = Groups().free(index_set=ZZ)
+            sage: G.rank()
+            +Infinity
+            sage: G = Groups().free(index_set='abc')
+            sage: G.rank()
+            3
+            sage: G = Groups().free(index_set=[])
+            sage: G.rank()
+            0
+
+        ::
+
+            sage: G = Groups().Commutative().free(index_set=ZZ)
+            sage: G.rank()
+            +Infinity
+            sage: G = Groups().Commutative().free(index_set='abc')
+            sage: G.rank()
+            3
+            sage: G = Groups().Commutative().free(index_set=[])
+            sage: G.rank()
+            0
+        """
+        return self.group_generators().cardinality()
+
+    @cached_method
+    def group_generators(self):
+        """
+        Return the group generators of ``self``.
+
+        EXAMPLES::
+
+            sage: G = Groups.free(index_set=ZZ)
+            sage: G.group_generators()
+            Lazy family (Generator map from Integer Ring to
+             Free group indexed by Integer Ring(i))_{i in Integer Ring}
+            sage: G = Groups().free(index_set='abcde')
+            sage: sorted(G.group_generators())
+            [F['a'], F['b'], F['c'], F['d'], F['e']]
+        """
+        if self._indices.cardinality() == infinity:
+            gen = PoorManMap(self.gen, domain=self._indices, codomain=self, name="Generator map")
+            return Family(self._indices, gen)
+        return Family(self._indices, self.gen)
+
+    gens = group_generators
+
+
+class IndexedFreeGroup(IndexedGroup, Group):
+    """
+    An indexed free group.
+
+    EXAMPLES::
+
+        sage: G = Groups().free(index_set=ZZ)
+        sage: G
+        Free group indexed by Integer Ring
+        sage: G = Groups().free(index_set='abcde')
+        sage: G
+        Free group indexed by {'a', 'b', 'c', 'd', 'e'}
+    """
+    def __init__(self, indices, prefix, category=None, **kwds):
+        """
+        Initialize ``self``.
+
+        TESTS::
+
+            sage: G = Groups().free(index_set=ZZ)
+            sage: TestSuite(G).run()
+            sage: G = Groups().free(index_set='abc')
+            sage: TestSuite(G).run()
+        """
+        category = Groups().or_subcategory(category)
+        IndexedGroup.__init__(self, indices, prefix, category, **kwds)
+
+    def _repr_(self):
+        """
+        Return a string representation of ``self``.
+
+        TESTS::
+
+            sage: Groups().free(index_set=ZZ)       # indirect doctest
+            Free group indexed by Integer Ring
+        """
+        return 'Free group indexed by {}'.format(self._indices)
+
+    @cached_method
+    def one(self):
+        """
+        Return the identity element of ``self``.
+
+        EXAMPLES::
+
+            sage: G = Groups().free(ZZ)
+            sage: G.one()
+            1
+        """
+        return self.element_class(self, ())
+
+    def gen(self, x):
+        """
+        The generator indexed by ``x`` of ``self``.
+
+        EXAMPLES::
+
+            sage: G = Groups().free(index_set=ZZ)
+            sage: G.gen(0)
+            F[0]
+            sage: G.gen(2)
+            F[2]
+        """
+        if x not in self._indices:
+            raise IndexError("{} is not in the index set".format(x))
+        try:
+            return self.element_class(self, ((self._indices(x),1),))
+        except TypeError: # Backup (if it is a string)
+            return self.element_class(self, ((x,1),))
+
+    class Element(IndexedFreeMonoidElement):
+        def __len__(self):
+            """
+            Return the length of ``self``.
+
+            EXAMPLES::
+
+                sage: G = Groups().free(index_set=ZZ)
+                sage: a,b,c,d,e = [G.gen(i) for i in range(5)]
+                sage: elt = a*c^-3*b^-2*a
+                sage: elt.length()
+                7
+                sage: len(elt)
+                7
+
+                sage: G = Groups().free(index_set=ZZ)
+                sage: a,b,c,d,e = [G.gen(i) for i in range(5)]
+                sage: elt = a*c^-3*b^-2*a
+                sage: elt.length()
+                7
+                sage: len(elt)
+                7
+            """
+            return sum(abs(exp) for gen,exp in self._monomial)
+
+        length = __len__
+
+        def _mul_(self, other):
+            """
+            Multiply ``self`` by ``other``.
+
+            EXAMPLES::
+
+                sage: G = Groups().free(index_set=ZZ)
+                sage: a,b,c,d,e = [G.gen(i) for i in range(5)]
+                sage: a*b^2*e*d
+                F[0]*F[1]^2*F[4]*F[3]
+                sage: (a*b^2*d^2) * (d^-4*b*e)
+                F[0]*F[1]^2*F[3]^-2*F[1]*F[4]
+                sage: (a*b^-2*d^2) * (d^-2*b^2*a^-1)
+                1
+            """
+            if not self._monomial:
+                return other
+            if not other._monomial:
+                return self
+
+            ret = list(self._monomial)
+            rhs = list(other._monomial)
+            while ret and rhs and ret[-1][0] == rhs[0][0]:
+                rhs[0] = (rhs[0][0], rhs[0][1] + ret.pop()[1])
+                if rhs[0][1] == 0:
+                    rhs.pop(0)
+            ret += rhs
+            return self.__class__(self.parent(), tuple(ret))
+
+        def __invert__(self):
+            """
+            Return the inverse of ``self``.
+
+            EXAMPLES::
+
+                sage: G = Groups().free(index_set=ZZ)
+                sage: a,b,c,d,e = [G.gen(i) for i in range(5)]
+                sage: x = a*b^2*e^-1*d; ~x
+                F[3]^-1*F[4]*F[1]^-2*F[0]^-1
+                sage: x * ~x
+                1
+            """
+            return self.__class__(self.parent(),
+                   tuple((x[0], -x[1]) for x in reversed(self._monomial)))
+
+        def to_word_list(self):
+            """
+            Return ``self`` as a word represented as a list whose entries
+            are the pairs ``(i, s)`` where ``i`` is the index and ``s`` is
+            the sign.
+
+            EXAMPLES::
+
+                sage: G = Groups().free(index_set=ZZ)
+                sage: a,b,c,d,e = [G.gen(i) for i in range(5)]
+                sage: x = a*b^2*e*a^-1
+                sage: x.to_word_list()
+                [(0, 1), (1, 1), (1, 1), (4, 1), (0, -1)]
+            """
+            sign = lambda x: 1 if x > 0 else -1 # It is never 0
+            return [ (k, sign(e)) for k,e in self._sorted_items()
+                     for dummy in range(abs(e))]
+
+
+class IndexedFreeAbelianGroup(IndexedGroup, AbelianGroup):
+    """
+    An indexed free abelian group.
+
+    EXAMPLES::
+
+        sage: G = Groups().Commutative().free(index_set=ZZ)
+        sage: G
+        Free abelian group indexed by Integer Ring
+        sage: G = Groups().Commutative().free(index_set='abcde')
+        sage: G
+        Free abelian group indexed by {'a', 'b', 'c', 'd', 'e'}
+    """
+    def __init__(self, indices, prefix, category=None, **kwds):
+        """
+        Initialize ``self``.
+
+        TESTS::
+
+            sage: G = Groups().Commutative().free(index_set=ZZ)
+            sage: TestSuite(G).run()
+            sage: G = Groups().Commutative().free(index_set='abc')
+            sage: TestSuite(G).run()
+        """
+        category = Groups().or_subcategory(category)
+        IndexedGroup.__init__(self, indices, prefix, category, **kwds)
+
+    def _repr_(self):
+        """
+        TESTS::
+
+            sage: Groups.Commutative().free(index_set=ZZ)
+            Free abelian group indexed by Integer Ring
+        """
+        return 'Free abelian group indexed by {}'.format(self._indices)
+
+    def _element_constructor_(self, x=None):
+        """
+        Create an element of ``self`` from ``x``.
+
+        EXAMPLES::
+
+            sage: G = Groups().Commutative().free(index_set=ZZ)
+            sage: G(G.gen(2))
+            F[2]
+            sage: G([[1, 3], [-2, 12]])
+            F[-2]^12*F[1]^3
+            sage: G({1: 3, -2: 12})
+            F[-2]^12*F[1]^3
+            sage: G(-5)
+            F[-5]
+
+        TESTS::
+
+            sage: G([(1, 3), (1, -5)])
+            F[1]^-2
+
+            sage: G([(42, 0)])
+            1
+            sage: G([(42, 3), (42, -3)])
+            1
+            sage: G({42: 0})
+            1
+        """
+        if isinstance(x, (list, tuple)):
+            d = {}
+            for k, v in x:
+                if k in d:
+                    d[k] += v
+                else:
+                    d[k] = v
+            x = d
+        if isinstance(x, dict):
+            x = {k: v for k, v in x.items() if v != 0}
+        return IndexedGroup._element_constructor_(self, x)
+
+    @cached_method
+    def one(self):
+        """
+        Return the identity element of ``self``.
+
+        EXAMPLES::
+
+            sage: G = Groups().Commutative().free(index_set=ZZ)
+            sage: G.one()
+            1
+        """
+        return self.element_class(self, {})
+
+    def gen(self, x):
+        """
+        The generator indexed by ``x`` of ``self``.
+
+        EXAMPLES::
+
+            sage: G = Groups().Commutative().free(index_set=ZZ)
+            sage: G.gen(0)
+            F[0]
+            sage: G.gen(2)
+            F[2]
+        """
+        if x not in self._indices:
+            raise IndexError("{} is not in the index set".format(x))
+        try:
+            return self.element_class(self, {self._indices(x):1})
+        except TypeError: # Backup (if it is a string)
+            return self.element_class(self, {x:1})
+
+    class Element(IndexedFreeAbelianMonoidElement, IndexedFreeGroup.Element):
+        def _mul_(self, other):
+            """
+            Multiply ``self`` by ``other``.
+
+            EXAMPLES::
+
+                sage: G = Groups().Commutative().free(index_set=ZZ)
+                sage: a,b,c,d,e = [G.gen(i) for i in range(5)]
+                sage: a*b^2*e^-1*d
+                F[0]*F[1]^2*F[3]*F[4]^-1
+                sage: (a*b^2*d^2) * (d^-4*b^-2*e)
+                F[0]*F[3]^-2*F[4]
+                sage: (a*b^-2*d^2) * (d^-2*b^2*a^-1)
+                1
+            """
+            return self.__class__(self.parent(),
+                                  blas.add(self._monomial, other._monomial))
+
+        def __invert__(self):
+            """
+            Return the inverse of ``self``.
+
+            EXAMPLES::
+
+                sage: G = Groups().Commutative().free(index_set=ZZ)
+                sage: a,b,c,d,e = [G.gen(i) for i in range(5)]
+                sage: x = a*b^2*e^-1*d; ~x
+                F[0]^-1*F[1]^-2*F[3]^-1*F[4]
+                sage: x * ~x
+                1
+            """
+            return self ** -1
+
+        def __floordiv__(self, a):
+            """
+            Return the division of ``self`` by ``a``.
+
+            EXAMPLES::
+
+                sage: G = Groups().Commutative().free(index_set=ZZ)
+                sage: a,b,c,d,e = [G.gen(i) for i in range(5)]
+                sage: elt = a*b*c^3*d^2; elt
+                F[0]*F[1]*F[2]^3*F[3]^2
+                sage: elt // a
+                F[1]*F[2]^3*F[3]^2
+                sage: elt // c
+                F[0]*F[1]*F[2]^2*F[3]^2
+                sage: elt // (a*b*d^2)
+                F[2]^3
+                sage: elt // a^4
+                F[0]^-3*F[1]*F[2]^3*F[3]^2
+            """
+            return self * ~a
+
+        def __pow__(self, n):
+            """
+            Raise ``self`` to the power of ``n``.
+
+            EXAMPLES::
+
+                sage: G = Groups().Commutative().free(index_set=ZZ)
+                sage: a,b,c,d,e = [G.gen(i) for i in range(5)]
+                sage: x = a*b^2*e^-1*d; x
+                F[0]*F[1]^2*F[3]*F[4]^-1
+                sage: x^3
+                F[0]^3*F[1]^6*F[3]^3*F[4]^-3
+                sage: x^0
+                1
+                sage: x^-3
+                F[0]^-3*F[1]^-6*F[3]^-3*F[4]^3
+            """
+            if not isinstance(n, (int, Integer)):
+                raise TypeError("Argument n (= {}) must be an integer".format(n))
+            if n == 1:
+                return self
+            if n == 0:
+                return self.parent().one()
+            return self.__class__(self.parent(), {k:v*n for k,v in self._monomial.items()})

sage/libs/all__sagemath_combinat.py

@@ -0,0 +1,6 @@
+# sage_setup: distribution = sagemath-combinat
+from sage.misc.lazy_import import lazy_import
+
+lazy_import('sage.libs.symmetrica', 'all', as_='symmetrica')
+
+del lazy_import

sage/libs/lrcalc/__init__.py

@@ -0,0 +1 @@
+# sage_setup: distribution = sagemath-combinat