passagemath-categories 10.6.31rc3__cp314-cp314-macosx_13_0_arm64.whl

sage/categories/euclidean_domains.py

@@ -0,0 +1,271 @@
+# sage_setup: distribution = sagemath-categories
+r"""
+Euclidean domains
+
+AUTHORS:
+
+- Teresa Gomez-Diaz (2008): initial version
+
+- Julian Rueth (2013-09-13): added euclidean degree, quotient remainder, and
+  their tests
+"""
+# ****************************************************************************
+#  Copyright (C) 2008 Teresa Gomez-Diaz (CNRS) <Teresa.Gomez-Diaz@univ-mlv.fr>
+#                2013 Julian Rueth <julian.rueth@fsfe.org>
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#                  https://www.gnu.org/licenses/
+# *****************************************************************************
+
+from sage.categories.category_singleton import Category_singleton
+from sage.categories.principal_ideal_domains import PrincipalIdealDomains
+from sage.misc.abstract_method import abstract_method
+from sage.structure.element import coerce_binop
+from sage.structure.sequence import Sequence
+
+
+class EuclideanDomains(Category_singleton):
+    """
+    The category of constructive euclidean domains, i.e., one can divide
+    producing a quotient and a remainder where the remainder is either zero or
+    its :meth:`ElementMethods.euclidean_degree` is smaller than the divisor.
+
+    EXAMPLES::
+
+      sage: EuclideanDomains()
+      Category of euclidean domains
+      sage: EuclideanDomains().super_categories()
+      [Category of principal ideal domains]
+
+    TESTS::
+
+        sage: TestSuite(EuclideanDomains()).run()
+    """
+    def super_categories(self):
+        """
+        EXAMPLES::
+
+            sage: EuclideanDomains().super_categories()
+            [Category of principal ideal domains]
+        """
+        return [PrincipalIdealDomains()]
+
+    class ParentMethods:
+        def is_euclidean_domain(self):
+            """
+            Return ``True``, since this in an object of the category of Euclidean domains.
+
+            EXAMPLES::
+
+                sage: Parent(QQ,category=EuclideanDomains()).is_euclidean_domain()
+                True
+            """
+            return True
+
+        def gcd_free_basis(self, elts):
+            r"""
+            Compute a set of coprime elements that can be used to express the
+            elements of ``elts``.
+
+            INPUT:
+
+            - ``elts`` -- a sequence of elements of ``self``
+
+            OUTPUT:
+
+            A GCD-free basis (also called a coprime base) of ``elts``; that is,
+            a set of pairwise relatively prime elements of ``self`` such that
+            any element of ``elts`` can be written as a product of elements of
+            the set.
+
+            ALGORITHM:
+
+            Naive implementation of the algorithm described in Section 4.8 of
+            Bach & Shallit [BS1996]_.
+
+            EXAMPLES::
+
+                sage: ZZ.gcd_free_basis([1])
+                []
+                sage: ZZ.gcd_free_basis([4, 30, 14, 49])
+                [2, 15, 7]
+
+                sage: Pol.<x> = QQ[]
+                sage: sorted(Pol.gcd_free_basis([
+                ....:     (x+1)^3*(x+2)^3*(x+3), (x+1)*(x+2)*(x+3),
+                ....:     (x+1)*(x+2)*(x+4)]))
+                [x + 3, x + 4, x^2 + 3*x + 2]
+
+            TESTS::
+
+                sage: R.<x> = QQ[]
+                sage: QQ.gcd_free_basis([x+1,x+2])
+                Traceback (most recent call last):
+                ...
+                TypeError: unable to convert x + 1 to an element of Rational Field
+            """
+            def refine(a, b):
+                g = a.gcd(b)
+                if g.is_unit():
+                    return (a, set(), b)
+                l1, s1, r1 = refine(a//g, g)
+                l2, s2, r2 = refine(r1, b//g)
+                s1.update(s2)
+                s1.add(l2)
+                return (l1, s1, r2)
+            elts = Sequence(elts, universe=self)
+            res = set()
+            if len(elts) == 1:
+                res.update(elts)
+            else:
+                r = elts[-1]
+                for t in self.gcd_free_basis(elts[:-1]):
+                    l, s, r = refine(t, r)
+                    res.update(s)
+                    res.add(l)
+                res.add(r)
+            units = [x for x in res if x.is_unit()]
+            res.difference_update(units)
+            return Sequence(res, universe=self, check=False)
+
+        def _test_euclidean_degree(self, **options):
+            r"""
+            Test that the assumptions on a Euclidean degree are met.
+
+            EXAMPLES::
+
+                sage: R.<x> = QQ[]
+                sage: R._test_euclidean_degree()
+
+            .. SEEALSO::
+
+                :meth:`_test_quo_rem`
+            """
+            tester = self._tester(**options)
+            S = [s for s in tester.some_elements() if not s.is_zero()]
+
+            min_degree = self.one().euclidean_degree()
+
+            from sage.rings.semirings.non_negative_integer_semiring import NN
+            for a in S:
+                tester.assertIn(a.euclidean_degree(), NN)
+                tester.assertGreaterEqual(a.euclidean_degree(), min_degree)
+                tester.assertEqual(a.euclidean_degree() == min_degree, a.is_unit())
+
+            from sage.misc.misc import some_tuples
+            for a,b in some_tuples(S, 2, tester._max_runs):
+                p = a * b
+                # For rings which are not exact, we might get something that
+                #   acts like a zero divisor.
+                # Therefore we skip the product if it evaluates to zero.
+                # Let the category of Domains handle the test for zero divisors.
+                if p.is_zero():
+                    continue
+                tester.assertLessEqual(a.euclidean_degree(), p.euclidean_degree())
+
+        def _test_quo_rem(self, **options):
+            r"""
+            Test that the assumptions on a quotient with remainder of an
+            euclidean domain are met.
+
+            EXAMPLES::
+
+                sage: R.<x> = QQ[]
+                sage: R._test_quo_rem()
+
+            .. SEEALSO::
+
+                :meth:`_test_euclidean_degree`
+            """
+            tester = self._tester(**options)
+            S = tester.some_elements()
+            from sage.misc.misc import some_tuples
+            for a,b in some_tuples(S, 2, tester._max_runs):
+                if b.is_zero():
+                    tester.assertRaises(ZeroDivisionError, lambda: a.quo_rem(b))
+                else:
+                    q,r = a.quo_rem(b)
+                    tester.assertIn(q, self)
+                    tester.assertIn(r, self)
+                    tester.assertEqual(a,q*b+r)
+                    if r != 0:
+                        tester.assertLess(r.euclidean_degree(), b.euclidean_degree())
+
+    class ElementMethods:
+        @abstract_method
+        def euclidean_degree(self):
+            r"""
+            Return the degree of this element as an element of a Euclidean
+            domain, i.e., for elements `a`, `b` the euclidean degree `f`
+            satisfies the usual properties:
+
+            1. if `b` is not zero, then there are elements `q` and `r` such
+               that `a = bq + r` with `r = 0` or `f(r) < f(b)`
+            2. if `a,b` are not zero, then `f(a) \leq f(ab)`
+
+            .. NOTE::
+
+                The name ``euclidean_degree`` was chosen because the euclidean
+                function has different names in different contexts, e.g.,
+                absolute value for integers, degree for polynomials.
+
+            OUTPUT:
+
+            For nonzero elements, a natural number. For the zero element, this
+            might raise an exception or produce some other output, depending on
+            the implementation.
+
+            EXAMPLES::
+
+                sage: R.<x> = QQ[]
+                sage: x.euclidean_degree()
+                1
+                sage: ZZ.one().euclidean_degree()
+                1
+            """
+
+        @coerce_binop
+        def gcd(self, other):
+            """
+            Return the greatest common divisor of this element and ``other``.
+
+            INPUT:
+
+            - ``other`` -- an element in the same ring as ``self``
+
+            ALGORITHM:
+
+            Algorithm 3.2.1 in [Coh1993]_.
+
+            EXAMPLES::
+
+                sage: R.<x> = PolynomialRing(QQ, sparse=True)
+                sage: EuclideanDomains().element_class.gcd(x,x+1)
+                -1
+            """
+            A = self
+            B = other
+            while not B.is_zero():
+                Q, R = A.quo_rem(B)
+                A = B
+                B = R
+            return A
+
+        @abstract_method
+        def quo_rem(self, other):
+            r"""
+            Return the quotient and remainder of the division of this element
+            by the nonzero element ``other``.
+
+            INPUT:
+
+            - ``other`` -- an element in the same euclidean domain
+
+            OUTPUT: a pair of elements
+
+            EXAMPLES::
+
+                sage: R.<x> = QQ[]
+                sage: x.quo_rem(x)
+                (1, 0)
+            """

sage/categories/examples/algebras_with_basis.py

@@ -0,0 +1,102 @@
+# sage_setup: distribution = sagemath-categories
+# sage.doctest: needs sage.combinat
+r"""
+Examples of algebras with basis
+"""
+#*****************************************************************************
+#  Copyright (C) 2008-2009 Nicolas M. Thiery <nthiery at users.sf.net>
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#                  http://www.gnu.org/licenses/
+#*****************************************************************************
+
+from sage.misc.cachefunc import cached_method
+from sage.sets.family import Family
+from sage.categories.algebras_with_basis import AlgebrasWithBasis
+from sage.combinat.free_module import CombinatorialFreeModule
+from sage.combinat.words.words import Words
+
+
+class FreeAlgebra(CombinatorialFreeModule):
+    r"""
+    An example of an algebra with basis: the free algebra.
+
+    This class illustrates a minimal implementation of an algebra with basis.
+    """
+
+    def __init__(self, R, alphabet=("a", "b", "c")):
+        """
+        EXAMPLES::
+
+            sage: A = AlgebrasWithBasis(QQ).example(); A                                # needs sage.modules
+            An example of an algebra with basis: the free algebra on the generators ('a', 'b', 'c') over Rational Field
+            sage: TestSuite(A).run()                                                    # needs sage.modules
+        """
+        self._alphabet = alphabet
+        CombinatorialFreeModule.__init__(self, R,
+                                         Words(alphabet, infinite=False),
+                                         category=AlgebrasWithBasis(R))
+
+    def _repr_(self):
+        """
+        EXAMPLES::
+
+            sage: AlgebrasWithBasis(QQ).example()  # indirect doctest                   # needs sage.modules
+            An example of an algebra with basis: the free algebra on the generators ('a', 'b', 'c') over Rational Field
+        """
+        return "An example of an algebra with basis: the free algebra on the generators %s over %s" % (self._alphabet, self.base_ring())
+
+    @cached_method
+    def one_basis(self):
+        """
+        Return the empty word, which index the one of this algebra,
+        as per :meth:`AlgebrasWithBasis.ParentMethods.one_basis`.
+
+        EXAMPLES::
+
+            sage: A = AlgebrasWithBasis(QQ).example()                                   # needs sage.modules
+            sage: A.one_basis()                                                         # needs sage.modules
+            word:
+            sage: A.one()                                                               # needs sage.modules
+            B[word: ]
+        """
+        return self.basis().keys()([])
+
+    def product_on_basis(self, w1, w2):
+        r"""
+        Product of basis elements, as per
+        :meth:`AlgebrasWithBasis.ParentMethods.product_on_basis`.
+
+        EXAMPLES::
+
+            sage: # needs sage.modules
+            sage: A = AlgebrasWithBasis(QQ).example()
+            sage: Words = A.basis().keys()
+            sage: A.product_on_basis(Words("acb"), Words("cba"))
+            B[word: acbcba]
+            sage: (a,b,c) = A.algebra_generators()
+            sage: a * (1-b)^2 * c
+            B[word: abbc] - 2*B[word: abc] + B[word: ac]
+        """
+        return self.basis()[w1 + w2]
+
+    @cached_method
+    def algebra_generators(self):
+        r"""
+        Return the generators of this algebra, as per :meth:`~.magmatic_algebras.MagmaticAlgebras.ParentMethods.algebra_generators`.
+
+        EXAMPLES::
+
+            sage: A = AlgebrasWithBasis(QQ).example(); A                                # needs sage.modules
+            An example of an algebra with basis: the free algebra on the generators ('a', 'b', 'c') over Rational Field
+            sage: A.algebra_generators()                                                # needs sage.modules
+            Family (B[word: a], B[word: b], B[word: c])
+        """
+        Words = self.basis().keys()
+        return Family( [self.monomial(Words(a)) for a in self._alphabet] )
+        # FIXME: use this once the keys argument of FiniteFamily will be honoured
+        # for the specifying the order of the elements in the family
+        #return Family(self._alphabet, lambda a: self.term(self.basis().keys()(a)))
+
+
+Example = FreeAlgebra

sage/categories/examples/all.py

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

sage/categories/examples/commutative_additive_monoids.py

@@ -0,0 +1,130 @@
+# sage_setup: distribution = sagemath-categories
+"""
+Examples of commutative additive monoids
+"""
+#*****************************************************************************
+#  Copyright (C) 2008-2009 Nicolas M. Thiery <nthiery at users.sf.net>
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#                  http://www.gnu.org/licenses/
+#******************************************************************************
+
+from sage.misc.cachefunc import cached_method
+from sage.structure.parent import Parent
+from sage.categories.commutative_additive_monoids import CommutativeAdditiveMonoids
+from .commutative_additive_semigroups import FreeCommutativeAdditiveSemigroup
+
+
+class FreeCommutativeAdditiveMonoid(FreeCommutativeAdditiveSemigroup):
+    r"""
+    An example of a commutative additive monoid: the free commutative monoid.
+
+    This class illustrates a minimal implementation of a commutative monoid.
+
+    EXAMPLES::
+
+        sage: S = CommutativeAdditiveMonoids().example(); S
+        An example of a commutative monoid: the free commutative monoid generated by ('a', 'b', 'c', 'd')
+
+        sage: S.category()
+        Category of commutative additive monoids
+
+    This is the free semigroup generated by::
+
+        sage: S.additive_semigroup_generators()
+        Family (a, b, c, d)
+
+    with product rule given by `a \times b = a` for all `a, b`::
+
+        sage: (a,b,c,d) = S.additive_semigroup_generators()
+
+    We conclude by running systematic tests on this commutative monoid::
+
+        sage: TestSuite(S).run(verbose = True)
+        running ._test_additive_associativity() . . . pass
+        running ._test_an_element() . . . pass
+        running ._test_cardinality() . . . pass
+        running ._test_category() . . . pass
+        running ._test_construction() . . . pass
+        running ._test_elements() . . .
+          Running the test suite of self.an_element()
+          running ._test_category() . . . pass
+          running ._test_eq() . . . pass
+          running ._test_new() . . . pass
+          running ._test_nonzero_equal() . . . pass
+          running ._test_not_implemented_methods() . . . pass
+          running ._test_pickling() . . . pass
+          pass
+        running ._test_elements_eq_reflexive() . . . pass
+        running ._test_elements_eq_symmetric() . . . pass
+        running ._test_elements_eq_transitive() . . . pass
+        running ._test_elements_neq() . . . pass
+        running ._test_eq() . . . pass
+        running ._test_new() . . . pass
+        running ._test_not_implemented_methods() . . . pass
+        running ._test_pickling() . . . pass
+        running ._test_some_elements() . . . pass
+        running ._test_zero() . . . pass
+    """
+
+    def __init__(self, alphabet=('a','b','c','d')):
+        r"""
+        The free commutative monoid.
+
+        INPUT:
+
+        - ``alphabet`` -- tuple of strings; the generators of the monoid
+
+        EXAMPLES::
+
+            sage: M = CommutativeAdditiveMonoids().example(alphabet=('a','b','c')); M
+            An example of a commutative monoid: the free commutative monoid generated by ('a', 'b', 'c')
+
+        TESTS::
+
+            sage: TestSuite(M).run()
+        """
+        self.alphabet = alphabet
+        Parent.__init__(self, category=CommutativeAdditiveMonoids())
+
+    def _repr_(self):
+        r"""
+        TESTS::
+
+            sage: M = CommutativeAdditiveMonoids().example(alphabet=('a','b','c'))
+            sage: M._repr_()
+            "An example of a commutative monoid: the free commutative monoid generated by ('a', 'b', 'c')"
+        """
+        return "An example of a commutative monoid: the free commutative monoid generated by %s" % (self.alphabet,)
+
+    @cached_method
+    def zero(self):
+        r"""
+        Return the zero of this additive monoid, as per :meth:`CommutativeAdditiveMonoids.ParentMethods.zero`.
+
+        EXAMPLES::
+
+            sage: M = CommutativeAdditiveMonoids().example(); M
+            An example of a commutative monoid: the free commutative monoid generated by ('a', 'b', 'c', 'd')
+            sage: M.zero()
+            0
+        """
+        return self(())
+
+    class Element(FreeCommutativeAdditiveSemigroup.Element):
+        def __bool__(self) -> bool:
+            """
+            Check if ``self`` is not the zero of the monoid
+
+            EXAMPLES::
+
+                sage: M = CommutativeAdditiveMonoids().example()
+                sage: bool(M.zero())
+                False
+                sage: [bool(m) for m in M.additive_semigroup_generators()]
+                [True, True, True, True]
+            """
+            return any(self.value.values())
+
+
+Example = FreeCommutativeAdditiveMonoid