passagemath-categories 10.6.32__cp314-cp314t-musllinux_1_2_aarch64.whl

sage/categories/finite_fields.py

@@ -0,0 +1,252 @@
+# sage_setup: distribution = sagemath-categories
+r"""
+Finite fields
+"""
+# ****************************************************************************
+#  Copyright (C) 2005      David Kohel <kohel@maths.usyd.edu>
+#                          William Stein <wstein@math.ucsd.edu>
+#                2008      Teresa Gomez-Diaz (CNRS) <Teresa.Gomez-Diaz@univ-mlv.fr>
+#                2008-2009 Nicolas M. Thiery <nthiery at users.sf.net>
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#                  https://www.gnu.org/licenses/
+# *****************************************************************************
+
+from sage.categories.category_with_axiom import CategoryWithAxiom
+from sage.categories.enumerated_sets import EnumeratedSets
+
+
+class FiniteFields(CategoryWithAxiom):
+    """
+    The category of finite fields.
+
+    EXAMPLES::
+
+        sage: K = FiniteFields(); K
+        Category of finite enumerated fields
+
+    A finite field is a finite monoid with the structure of a field;
+    it is currently assumed to be enumerated::
+
+        sage: K.super_categories()
+        [Category of fields,
+         Category of finite commutative rings,
+         Category of finite enumerated sets]
+
+    Some examples of membership testing and coercion::
+
+        sage: FiniteField(17) in K
+        True
+        sage: RationalField() in K
+        False
+        sage: K(RationalField())
+        Traceback (most recent call last):
+        ...
+        TypeError: unable to canonically associate a finite field to Rational Field
+
+    TESTS::
+
+        sage: K is Fields().Finite()
+        True
+        sage: TestSuite(K).run()
+    """
+
+    def extra_super_categories(self):
+        r"""
+        Any finite field is assumed to be endowed with an enumeration.
+
+        TESTS::
+
+            sage: Fields().Finite().extra_super_categories()
+            [Category of finite enumerated sets]
+            sage: FiniteFields().is_subcategory(FiniteEnumeratedSets())
+            True
+        """
+        return [EnumeratedSets().Finite()]
+
+    def __contains__(self, x):
+        """
+        EXAMPLES::
+
+            sage: GF(4, "a") in FiniteFields()                                          # needs sage.rings.finite_rings
+            True
+            sage: QQ in FiniteFields()
+            False
+            sage: IntegerModRing(4) in FiniteFields()
+            False
+        """
+        from sage.categories.fields import Fields
+        return x in Fields() and x.is_finite()
+
+    # As is, this does no more than the usual __call__ of Category, but for the error message
+    def _call_(self, x):
+        """
+        EXAMPLES::
+
+            sage: FiniteFields()(GF(4, "a"))                                            # needs sage.rings.finite_rings
+            Finite Field in a of size 2^2
+            sage: FiniteFields()(RationalField())   # indirect doctest
+            Traceback (most recent call last):
+            ...
+            TypeError: unable to canonically associate a finite field to Rational Field
+        """
+        raise TypeError("unable to canonically associate a finite field to %s" % x)
+        # TODO: local dvr ring?
+
+    class ParentMethods:
+        def is_perfect(self):
+            r"""
+            Return whether this field is perfect, i.e., every element has a `p`-th
+            root. Always returns ``True`` since finite fields are perfect.
+
+            EXAMPLES::
+
+                sage: GF(2).is_perfect()
+                True
+            """
+            return True
+
+        def zeta_order(self):
+            """
+            Return the order of the distinguished root of unity in ``self``.
+
+            EXAMPLES::
+
+                sage: # needs sage.rings.finite_rings
+                sage: GF(9,'a').zeta_order()
+                8
+                sage: GF(9,'a').zeta()
+                a
+                sage: GF(9,'a').zeta().multiplicative_order()
+                8
+            """
+            return self.order() - 1
+
+        def zeta(self, n=None):
+            """
+            Return an element of multiplicative order ``n`` in this finite
+            field. If there is no such element, raise :exc:`ValueError`.
+
+            .. WARNING::
+
+                In general, this returns an arbitrary element of the correct
+                order. There are no compatibility guarantees:
+                ``F.zeta(9)^3`` may not be equal to ``F.zeta(3)``.
+
+            EXAMPLES::
+
+                sage: # needs sage.rings.finite_rings
+                sage: k = GF(7)
+                sage: k.zeta()
+                3
+                sage: k.zeta().multiplicative_order()
+                6
+                sage: k.zeta(3)
+                2
+                sage: k.zeta(3).multiplicative_order()
+                3
+                sage: k = GF(49, 'a')
+                sage: k.zeta().multiplicative_order()
+                48
+                sage: k.zeta(6)
+                3
+                sage: k.zeta(5)
+                Traceback (most recent call last):
+                ...
+                ValueError: no 5th root of unity in Finite Field in a of size 7^2
+
+            Even more examples::
+
+                sage: # needs sage.rings.finite_rings
+                sage: GF(9,'a').zeta_order()
+                8
+                sage: GF(9,'a').zeta()
+                a
+                sage: GF(9,'a').zeta(4)
+                a + 1
+                sage: GF(9,'a').zeta()^2
+                a + 1
+
+            This works even in very large finite fields, provided that ``n``
+            can be factored (see :issue:`25203`)::
+
+                sage: # needs sage.rings.finite_rings
+                sage: k.<a> = GF(2^2000)
+                sage: p = 8877945148742945001146041439025147034098690503591013177336356694416517527310181938001
+                sage: z = k.zeta(p)
+                sage: z
+                a^1999 + a^1996 + a^1995 + a^1994 + ... + a^7 + a^5 + a^4 + 1
+                sage: z ^ p
+                1
+            """
+            if n is None:
+                return self.multiplicative_generator()
+
+            from sage.rings.integer import Integer
+            n = Integer(n)
+            grouporder = self.order() - 1
+            co_order = grouporder // n
+            if co_order * n != grouporder:
+                raise ValueError("no {}th root of unity in {}".format(n, self))
+
+            # If the co_order is small or we know a multiplicative
+            # generator, use a multiplicative generator
+            mg = self.multiplicative_generator
+            if mg.cache is not None or co_order <= 500000:
+                return mg() ** co_order
+            return self._element_of_factored_order(n.factor())
+
+        def _element_of_factored_order(self, F):
+            """
+            Return an element of ``self`` of order ``n`` where ``n`` is
+            given in factored form.
+
+            This is copied from the cython implementation in
+            ``finite_field_base.pyx`` which is kept as it may be faster.
+
+            INPUT:
+
+            - ``F`` -- the factorization of the required order. The order
+              must be a divisor of ``self.order() - 1`` but this is not
+              checked.
+
+            EXAMPLES::
+
+                sage: # needs sage.rings.finite_rings
+                sage: k = Zmod(1913)
+                sage: k in Fields()  # to let k be a finite field
+                True
+                sage: k._element_of_factored_order(factor(1912))
+                3
+            """
+            from sage.rings.integer import Integer
+            n = Integer(1)
+            primes = []
+            for p, e in F:
+                primes.append(p)
+                n *= p**e
+
+            N = self.order() - 1
+            c = N // n
+
+            # We check whether (x + g)^c has the required order, where
+            # x runs through the finite field.
+            # This has the advantage that g is the first element we try,
+            # so if that was a chosen to be a multiplicative generator,
+            # we are done immediately. Second, the PARI finite field
+            # iterator gives all the constant elements first, so we try
+            # (g+(constant))^c before anything else.
+            g = self.gen()
+            if g == self.one():
+                # this allows to handle the ring Integers(prime)
+                g = self.multiplicative_generator()
+            for x in self:
+                a = (g + x)**c
+                if not a:
+                    continue
+                if all(a**(n // p) != 1 for p in primes):
+                    return a
+            raise AssertionError("no element found")
+
+    class ElementMethods:
+        pass

sage/categories/finite_groups.py

@@ -0,0 +1,256 @@
+# sage_setup: distribution = sagemath-categories
+# sage.doctest: needs sage.groups
+r"""
+Finite groups
+"""
+# ****************************************************************************
+#  Copyright (C) 2010-2013 Nicolas M. Thiery <nthiery at users.sf.net>
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#                  https://www.gnu.org/licenses/
+# *****************************************************************************
+
+from sage.categories.category_with_axiom import CategoryWithAxiom
+from sage.categories.algebra_functor import AlgebrasCategory
+
+
+class FiniteGroups(CategoryWithAxiom):
+    r"""
+    The category of finite (multiplicative) groups.
+
+    EXAMPLES::
+
+        sage: C = FiniteGroups(); C
+        Category of finite groups
+        sage: C.super_categories()
+        [Category of finite monoids, Category of groups]
+        sage: C.example()                                                               # needs sage.modules
+        General Linear Group of degree 2 over Finite Field of size 3
+
+    TESTS::
+
+        sage: TestSuite(C).run()
+    """
+
+    def example(self):
+        """
+        Return an example of finite group, as per
+        :meth:`Category.example`.
+
+        EXAMPLES::
+
+            sage: G = FiniteGroups().example(); G                                       # needs sage.modules
+            General Linear Group of degree 2 over Finite Field of size 3
+        """
+        from sage.groups.matrix_gps.linear import GL
+        return GL(2,3)
+
+    class ParentMethods:
+
+        def semigroup_generators(self):
+            """
+            Return semigroup generators for ``self``.
+
+            For finite groups, the group generators are also semigroup
+            generators. Hence, this default implementation calls
+            :meth:`~sage.categories.groups.Groups.ParentMethods.group_generators`.
+
+            EXAMPLES::
+
+                sage: A = AlternatingGroup(4)
+                sage: A.semigroup_generators()
+                Family ((1,2,3), (2,3,4))
+            """
+            return self.group_generators()
+
+        def monoid_generators(self):
+            """
+            Return monoid generators for ``self``.
+
+            For finite groups, the group generators are also monoid
+            generators. Hence, this default implementation calls
+            :meth:`~sage.categories.groups.Groups.ParentMethods.group_generators`.
+
+            EXAMPLES::
+
+                sage: A = AlternatingGroup(4)
+                sage: A.monoid_generators()
+                Family ((1,2,3), (2,3,4))
+            """
+            return self.group_generators()
+
+        def cardinality(self):
+            """
+            Return the cardinality of ``self``, as per
+            :meth:`EnumeratedSets.ParentMethods.cardinality`.
+
+            This default implementation calls :meth:`.order` if
+            available, and otherwise resorts to
+            :meth:`._cardinality_from_iterator`. This is for backward
+            compatibility only. Finite groups should override this
+            method instead of :meth:`.order`.
+
+            EXAMPLES:
+
+            We need to use a finite group which uses this default
+            implementation of cardinality::
+
+                sage: G = groups.misc.SemimonomialTransformation(GF(5), 3); G           # needs sage.rings.number_field
+                Semimonomial transformation group over Finite Field of size 5 of degree 3
+                sage: G.cardinality.__module__                                          # needs sage.rings.number_field
+                'sage.categories.finite_groups'
+                sage: G.cardinality()                                                   # needs sage.rings.number_field
+                384
+            """
+            if hasattr(self, 'order'):
+                return self.order()
+            return self._cardinality_from_iterator()
+
+        def some_elements(self):
+            """
+            Return some elements of ``self``.
+
+            EXAMPLES::
+
+                sage: A = AlternatingGroup(4)
+                sage: A.some_elements()
+                Family ((1,2,3), (2,3,4))
+            """
+            return self.group_generators()
+
+        # TODO: merge with that of finite semigroups
+        def cayley_graph_disabled(self, connecting_set=None):
+            """
+
+            AUTHORS:
+
+            - Bobby Moretti (2007-08-10)
+
+            - Robert Miller (2008-05-01): editing
+            """
+            if connecting_set is None:
+                connecting_set = self.group_generators()
+            else:
+                for g in connecting_set:
+                    if g not in self:
+                        raise RuntimeError("each element of the connecting set must be in the group")
+                connecting_set = [self(g) for g in connecting_set]
+            from sage.graphs.digraph import DiGraph
+            arrows = {}
+            for x in self:
+                arrows[x] = {}
+                for g in connecting_set:
+                    xg = x*g # cache the multiplication
+                    if not xg == x:
+                        arrows[x][xg] = g
+
+            return DiGraph(arrows, implementation='networkx')
+
+        def conjugacy_classes(self):
+            r"""
+            Return a list with all the conjugacy classes of the group.
+
+            This will eventually be a fall-back method for groups not defined
+            over GAP. Right now, it just raises a
+            :exc:`NotImplementedError`, until we include a non-GAP
+            way of listing the conjugacy classes representatives.
+
+            EXAMPLES::
+
+                sage: from sage.groups.group import FiniteGroup
+                sage: G = FiniteGroup()
+                sage: G.conjugacy_classes()
+                Traceback (most recent call last):
+                ...
+                NotImplementedError: Listing the conjugacy classes for group <sage.groups.group.FiniteGroup object at ...> is not implemented
+            """
+            raise NotImplementedError("Listing the conjugacy classes for group %s is not implemented" % self)
+
+        def conjugacy_classes_representatives(self):
+            r"""
+            Return a list of the conjugacy classes representatives of the group.
+
+            EXAMPLES::
+
+                sage: G = SymmetricGroup(3)
+                sage: G.conjugacy_classes_representatives()                             # needs sage.combinat
+                [(), (1,2), (1,2,3)]
+            """
+            return [C.representative() for C in self.conjugacy_classes()]
+
+    class ElementMethods:
+        pass
+
+    class Algebras(AlgebrasCategory):
+        def extra_super_categories(self):
+            r"""
+            Implement Maschke's theorem.
+
+            In characteristic 0 all finite group algebras are semisimple.
+
+            EXAMPLES::
+
+                sage: FiniteGroups().Algebras(QQ).is_subcategory(Algebras(QQ).Semisimple())
+                True
+                sage: FiniteGroups().Algebras(FiniteField(7)).is_subcategory(Algebras(FiniteField(7)).Semisimple())
+                False
+                sage: FiniteGroups().Algebras(ZZ).is_subcategory(Algebras(ZZ).Semisimple())
+                False
+                sage: FiniteGroups().Algebras(Fields()).is_subcategory(Algebras(Fields()).Semisimple())
+                False
+
+                sage: Cat = CommutativeAdditiveGroups().Finite()
+                sage: Cat.Algebras(QQ).is_subcategory(Algebras(QQ).Semisimple())
+                True
+                sage: Cat.Algebras(GF(7)).is_subcategory(Algebras(GF(7)).Semisimple())
+                False
+                sage: Cat.Algebras(ZZ).is_subcategory(Algebras(ZZ).Semisimple())
+                False
+                sage: Cat.Algebras(Fields()).is_subcategory(Algebras(Fields()).Semisimple())
+                False
+            """
+            from sage.categories.fields import Fields
+            K = self.base_ring()
+            if K in Fields() and K.characteristic() == 0:
+                from sage.categories.algebras import Algebras
+                return [Algebras(self.base_ring()).Semisimple()]
+            else:
+                return []
+
+        class ParentMethods:
+            def __init_extra__(self):
+                r"""
+                Implement Maschke's theorem.
+
+                EXAMPLES::
+
+                    sage: # needs sage.modules
+                    sage: G = groups.permutation.Dihedral(8)
+                    sage: A = G.algebra(GF(5))
+                    sage: A in Algebras.Semisimple
+                    True
+                    sage: A = G.algebra(Zmod(4))
+                    sage: A in Algebras.Semisimple
+                    False
+
+                    sage: # needs sage.modules
+                    sage: G = groups.misc.AdditiveCyclic(4)                             # needs sage.rings.number_field
+                    sage: Cat = CommutativeAdditiveGroups().Finite()
+                    sage: A = G.algebra(GF(5), category=Cat)
+                    sage: A in Algebras.Semisimple
+                    True
+                    sage: A = G.algebra(GF(2), category=Cat)
+                    sage: A in Algebras.Semisimple
+                    False
+                """
+                base_ring = self.base_ring()
+                group = self.group()
+                from sage.categories.fields import Fields
+                # If base_ring is of characteristic 0, this is handled
+                #    in the FiniteGroups.Algebras category
+                # Maschke's theorem: under some conditions, the algebra is semisimple.
+                if (base_ring in Fields
+                    and base_ring.characteristic() > 0
+                    and hasattr(group, "cardinality")
+                    and group.cardinality() % base_ring.characteristic() != 0):
+                    self._refine_category_(self.category().Semisimple())