passagemath-categories 10.6.32__cp314-cp314t-musllinux_1_2_aarch64.whl

sage/categories/examples/semigroups_cython.pyx

@@ -0,0 +1,221 @@
+# sage_setup: distribution = sagemath-categories
+r"""
+Examples of semigroups in cython
+"""
+
+from sage.structure.parent cimport Parent
+from sage.structure.element cimport Element
+from sage.categories.category import Category
+from sage.categories.semigroups import Semigroups
+from sage.categories.examples.semigroups import LeftZeroSemigroup as LeftZeroSemigroupPython
+from cpython.object cimport PyObject_RichCompare
+
+
+class IdempotentSemigroups(Category):
+    def super_categories(self):
+        """
+        EXAMPLES::
+
+            sage: from sage.categories.examples.semigroups_cython import IdempotentSemigroups
+            sage: IdempotentSemigroups().super_categories()
+            [Category of semigroups]
+        """
+        return [Semigroups()]
+
+    class ElementMethods:
+        def _pow_int(self, i):
+            """
+            EXAMPLES::
+
+                sage: from sage.categories.examples.semigroups_cython import LeftZeroSemigroup
+                sage: S = LeftZeroSemigroup()
+                sage: S(2)._pow_int(3)
+                2
+            """
+            assert i > 0
+            return self
+
+        def is_idempotent(self):
+            """
+            EXAMPLES::
+
+                sage: from sage.categories.examples.semigroups_cython import LeftZeroSemigroup
+                sage: S = LeftZeroSemigroup()
+                sage: S(2).is_idempotent()
+                True
+            """
+            return True
+
+
+cdef class LeftZeroSemigroupElement(Element):
+    cdef object _value
+
+    def __init__(self, parent, value):
+        """
+        EXAMPLES::
+
+            sage: from sage.categories.examples.semigroups_cython import LeftZeroSemigroup
+            sage: S = LeftZeroSemigroup()
+            sage: x = S(3)
+            sage: TestSuite(x).run()
+        """
+        Element.__init__(self, parent=parent)
+        self._value = value
+
+    def _repr_(self):
+        """
+        EXAMPLES::
+
+            sage: from sage.categories.examples.semigroups_cython import LeftZeroSemigroup
+            sage: S = LeftZeroSemigroup()
+            sage: S(3)                    # indirect doctest
+            3
+        """
+        return repr(self._value)
+
+    def __reduce__(self):
+        """
+        EXAMPLES::
+
+            sage: from sage.categories.examples.semigroups_cython import LeftZeroSemigroup
+            sage: S = LeftZeroSemigroup()
+            sage: x = S(3)
+            sage: x.__reduce__()
+            (<class 'sage.categories.examples.semigroups_cython.LeftZeroSemigroupElement'>,
+             (An example of a semigroup: the left zero semigroup, 3))
+        """
+        return LeftZeroSemigroupElement, (self._parent, self._value)
+
+    cpdef _richcmp_(self, other, int op):
+        """
+        EXAMPLES::
+
+            sage: from sage.categories.examples.semigroups_cython import LeftZeroSemigroup
+            sage: S = LeftZeroSemigroup()
+            sage: S(3) == S(3)
+            True
+            sage: S(3) == S(2)
+            False
+        """
+        left = (<LeftZeroSemigroupElement>self)._value
+        right = (<LeftZeroSemigroupElement>other)._value
+        return PyObject_RichCompare(left, right, op)
+
+    cpdef _mul_(self, other):
+        """
+        EXAMPLES::
+
+            sage: from sage.categories.examples.semigroups_cython import LeftZeroSemigroup
+            sage: S = LeftZeroSemigroup()
+            sage: S(2) * S(3)
+            2
+            sage: S(2)._mul_(S(3))
+            2
+        """
+        return self.parent().product(self, other)
+
+    def __pow__(self, i, dummy):
+        """
+        EXAMPLES::
+
+            sage: from sage.categories.examples.semigroups_cython import LeftZeroSemigroup
+            sage: S = LeftZeroSemigroup()
+            sage: S(2)^3
+            2
+        """
+        return self._pow_int(i)
+
+
+class LeftZeroSemigroup(LeftZeroSemigroupPython):
+    r"""
+    An example of semigroup.
+
+    This class illustrates a minimal implementation of a semi-group
+    where the element class is an extension type, and still gets code
+    from the category. The category itself must be a Python class
+    though.
+
+    This is purely a proof of concept. The code obviously needs refactorisation!
+
+    Comments:
+
+    - one cannot play ugly class surgery tricks (as with _mul_parent).
+      available operations should really be declared to the coercion model!
+
+    EXAMPLES::
+
+        sage: from sage.categories.examples.semigroups_cython import LeftZeroSemigroup
+        sage: S = LeftZeroSemigroup(); S
+        An example of a semigroup: the left zero semigroup
+
+    This is the semigroup which contains all sort of objects::
+
+        sage: S.some_elements()
+        [3, 42, 'a', 3.4, 'raton laveur']
+
+    with product rule given by `a \times b = a` for all `a,b`. ::
+
+        sage: S('hello') * S('world')
+        'hello'
+
+        sage: S(3)*S(1)*S(2)
+        3
+
+        sage: S(3)^12312321312321
+        3
+
+        sage: TestSuite(S).run(verbose = True)
+        running ._test_an_element() . . . pass
+        running ._test_associativity() . . . 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_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
+
+    That's really the only method which is obtained from the category ... ::
+
+        sage: S(42).is_idempotent
+        <bound method IdempotentSemigroups.ElementMethods.is_idempotent of 42>
+        sage: S(42).is_idempotent()
+        True
+
+        sage: S(42)._pow_int
+        <bound method IdempotentSemigroups.ElementMethods._pow_int of 42>
+        sage: S(42)^10
+        42
+
+        sage: S(42).is_idempotent
+        <bound method IdempotentSemigroups.ElementMethods.is_idempotent of 42>
+        sage: S(42).is_idempotent()
+        True
+    """
+
+    def __init__(self):
+        """
+        TESTS::
+
+            sage: from sage.categories.examples.semigroups_cython import LeftZeroSemigroup
+            sage: S = LeftZeroSemigroup()
+            sage: S.category()
+            Category of idempotent semigroups
+            sage: TestSuite(S).run()
+        """
+        Parent.__init__(self, category=IdempotentSemigroups())
+
+    Element = LeftZeroSemigroupElement

sage/categories/examples/semirings.py

@@ -0,0 +1,249 @@
+# sage_setup: distribution = sagemath-categories
+r"""
+Examples of semirings
+"""
+# ****************************************************************************
+#  Copyright (C) 2024 F. Chapoton <chapoton unistra.fr>
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#                  https://www.gnu.org/licenses/
+# ****************************************************************************
+
+from sage.categories.semirings import Semirings
+from sage.structure.element import Element
+from sage.structure.parent import Parent
+from sage.structure.unique_representation import UniqueRepresentation
+
+# semantic :
+# 0 => 0, empty;
+# 1 => 1, unique;
+# 2 => at least 2
+_ADD = [[0, 1, 2], [1, 2, 2], [2, 2, 2]]
+_PROD = [[0, 0, 0], [0, 1, 2], [0, 2, 2]]
+
+
+class Ternary(Element):
+    """
+    Elements of the ternary-logic ring.
+
+    The semantic is as follows:
+
+    - 0 -- the integer 0
+    - 1 -- the integer 1
+    - 2 -- some integer greater than 1
+
+    An alternative semantic is:
+
+    - 0 -- an empty set
+    - 1 -- a connected set
+    - 2 -- a disconnected set
+
+    The same semantic works for graphs instead of sets.
+    """
+    def __init__(self, parent, n):
+        """
+        Initialize one element.
+
+        TESTS::
+
+            sage: from sage.categories.examples.semirings import TernaryLogic
+            sage: S = TernaryLogic()
+            sage: S(4)
+            Traceback (most recent call last):
+            ...
+            ValueError: input not in (0,1,2)
+        """
+        if n not in [0, 1, 2]:
+            raise ValueError("input not in (0,1,2)")
+        self._n = n
+        Element.__init__(self, parent)
+
+    def _repr_(self):
+        """
+        Return the string representation.
+
+        TESTS::
+
+            sage: from sage.categories.examples.semirings import TernaryLogic
+            sage: S = TernaryLogic()
+            sage: [S(i) for i in range(3)]
+            [0, 1, many]
+        """
+        return ["0", "1", "many"][self._n]
+
+    def __eq__(self, other):
+        """
+        Test for equality.
+
+        TESTS::
+
+            sage: from sage.categories.examples.semirings import TernaryLogic
+            sage: S = TernaryLogic()
+            sage: S(1) == S(2)
+            False
+            sage: S(0) == 3
+            False
+        """
+        if not isinstance(other, Ternary):
+            return False
+        return self._n == other._n
+
+    def __ne__(self, other):
+        """
+        Test for non-equality.
+
+        TESTS::
+
+            sage: from sage.categories.examples.semirings import TernaryLogic
+            sage: S = TernaryLogic()
+            sage: S(1) != S(2)
+            True
+        """
+        return not (self == other)
+
+
+class TernaryLogic(UniqueRepresentation, Parent):
+    r"""
+    An example of a semiring.
+
+    This class illustrates a minimal implementation of a semiring.
+
+    EXAMPLES::
+
+        sage: S = Semirings().example(); S
+        An example of a semiring: the ternary-logic semiring
+
+    This is the semiring that contains 3 objects::
+
+        sage: S.some_elements()
+        [0, 1, many]
+
+    The product rule is as expected::
+
+        sage: S(1) * S(1)
+        1
+        sage: S(1) + S(1)
+        many
+
+    TESTS::
+
+        sage: TestSuite(S).run(verbose=True)
+        running ._test_additive_associativity() . . . pass
+        running ._test_an_element() . . . pass
+        running ._test_associativity() . . . pass
+        running ._test_cardinality() . . . pass
+        running ._test_category() . . . pass
+        running ._test_construction() . . . pass
+        running ._test_distributivity() . . . 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_one() . . . pass
+        running ._test_pickling() . . . pass
+        running ._test_prod() . . . pass
+        running ._test_some_elements() . . . pass
+        running ._test_zero() . . . pass
+    """
+    def __init__(self):
+        r"""
+        The ternary-logic semiring.
+
+        EXAMPLES::
+
+            sage: S = Semirings().example(); S
+            An example of a semiring: the ternary-logic semiring
+        """
+        Parent.__init__(self, category=Semirings())
+
+    def _repr_(self):
+        r"""
+        Return the string representation.
+
+        EXAMPLES::
+
+            sage: Semirings().example()._repr_()
+            'An example of a semiring: the ternary-logic semiring'
+        """
+        return "An example of a semiring: the ternary-logic semiring"
+
+    def summation(self, x, y):
+        r"""
+        Return the sum of ``x`` and ``y`` in the semiring as per
+        :meth:`Semirings.ParentMethods.summation`.
+
+        EXAMPLES::
+
+            sage: S = Semirings().example()
+            sage: S(1) + S(1)
+            many
+        """
+        assert x in self
+        assert y in self
+        return self(_ADD[x._n][y._n])
+
+    def one(self):
+        """
+        Return the unit of ``self``.
+
+        EXAMPLES::
+
+            sage: S = Semirings().example()
+            sage: S.one()
+            1
+        """
+        return self(1)
+
+    def product(self, x, y):
+        r"""
+        Return the product of ``x`` and ``y`` in the semiring as per
+        :meth:`Semirings.ParentMethods.product`.
+
+        EXAMPLES::
+
+            sage: S = Semirings().example()
+            sage: S(1) * S(2)
+            many
+        """
+        assert x in self
+        assert y in self
+        return self(_PROD[x._n][y._n])
+
+    def an_element(self):
+        r"""
+        Return an element of the semiring.
+
+        EXAMPLES::
+
+            sage: Semirings().example().an_element()
+            many
+        """
+        return self(2)
+
+    def some_elements(self):
+        r"""
+        Return a list of some elements of the semiring.
+
+        EXAMPLES::
+
+            sage: Semirings().example().some_elements()
+            [0, 1, many]
+        """
+        return [self(i) for i in [0, 1, 2]]
+
+    Element = Ternary
+
+
+Example = TernaryLogic