sagemathgh-39311: move krull_dimension to the category framework

    
This is moving the generic `krull_dimension` method to the category
framework for commutative rings.

Also deprecating the global `krull_dimension` function from the global
namespace.

### 📝 Checklist

- [x] The title is concise and informative.
- [x] The description explains in detail what this PR is about.
- [ ] I have linked a relevant issue or discussion.
- [x] I have created tests covering the changes.
- [x] I have updated the documentation and checked the documentation
preview.
    
URL: sagemath#39311
Reported by: Frédéric Chapoton
Reviewer(s): Kwankyu Lee

src/doc/en/thematic_tutorials/coercion_and_categories.rst

@@ -131,7 +131,6 @@ This base class provides a lot more methods than a general parent::
      'gens',
      'integral_closure',
      'is_field',
-     'krull_dimension',
      'ngens',
      'one',
      'order',

src/sage/categories/commutative_rings.py

@@ -59,6 +59,67 @@ class CommutativeRings(CategoryWithAxiom):
         False
     """
     class ParentMethods:
+        def krull_dimension(self):
+            """
+            Return the Krull dimension of this commutative ring.
+
+            The Krull dimension is the length of the longest ascending chain
+            of prime ideals.
+
+            This raises :exc:`NotImplementedError` by default
+            for generic commutative rings.
+
+            Fields and PIDs, with Krull dimension equal to 0 and 1,
+            respectively, have naive implementations of ``krull_dimension``.
+            Orders in number fields also have Krull dimension 1.
+
+            EXAMPLES:
+
+            Some polynomial rings::
+
+                sage: T.<x,y> = PolynomialRing(QQ,2); T
+                Multivariate Polynomial Ring in x, y over Rational Field
+                sage: T.krull_dimension()
+                2
+                sage: U.<x,y,z> = PolynomialRing(ZZ,3); U
+                Multivariate Polynomial Ring in x, y, z over Integer Ring
+                sage: U.krull_dimension()
+                4
+
+            All orders in number fields have Krull dimension 1, including
+            non-maximal orders::
+
+                sage: # needs sage.rings.number_field
+                sage: K.<i> = QuadraticField(-1)
+                sage: R = K.order(2*i); R
+                Order of conductor 2 generated by 2*i
+                 in Number Field in i with defining polynomial x^2 + 1 with i = 1*I
+                sage: R.is_maximal()
+                False
+                sage: R.krull_dimension()
+                1
+                sage: R = K.maximal_order(); R
+                Gaussian Integers generated by i in Number Field in i
+                 with defining polynomial x^2 + 1 with i = 1*I
+                sage: R.krull_dimension()
+                1
+
+            TESTS::
+
+                sage: R = CommutativeRing(ZZ)
+                sage: R.krull_dimension()
+                Traceback (most recent call last):
+                ...
+                NotImplementedError
+
+                sage: R = GF(9).galois_group().algebra(QQ)
+                sage: R.krull_dimension()
+                Traceback (most recent call last):
+                ...
+                NotImplementedError
+            """
+            raise NotImplementedError
+
         def is_commutative(self) -> bool:
             """
             Return whether the ring is commutative.

src/sage/categories/dedekind_domains.py

@@ -53,30 +53,6 @@ def krull_dimension(self):
                 sage: OK = K.ring_of_integers()                                             # needs sage.rings.number_field
                 sage: OK.krull_dimension()                                                  # needs sage.rings.number_field
                 1
-
-            The following are not Dedekind domains but have
-            a ``krull_dimension`` function::
-
-                sage: QQ.krull_dimension()
-                0
-                sage: T.<x,y> = PolynomialRing(QQ,2); T
-                Multivariate Polynomial Ring in x, y over Rational Field
-                sage: T.krull_dimension()
-                2
-                sage: U.<x,y,z> = PolynomialRing(ZZ,3); U
-                Multivariate Polynomial Ring in x, y, z over Integer Ring
-                sage: U.krull_dimension()
-                4
-
-                sage: # needs sage.rings.number_field
-                sage: K.<i> = QuadraticField(-1)
-                sage: R = K.order(2*i); R
-                Order of conductor 2 generated by 2*i
-                 in Number Field in i with defining polynomial x^2 + 1 with i = 1*I
-                sage: R.is_maximal()
-                False
-                sage: R.krull_dimension()
-                1
             """
             from sage.rings.integer_ring import ZZ
             return ZZ.one()

src/sage/categories/fields.py

@@ -192,6 +192,18 @@ def _call_(self, x):
     Finite = LazyImport('sage.categories.finite_fields', 'FiniteFields', at_startup=True)
 
     class ParentMethods:
+        def krull_dimension(self):
+            """
+            Return the Krull dimension of this field, which is 0.
+
+            EXAMPLES::
+
+                sage: QQ.krull_dimension()
+                0
+                sage: Frac(QQ['x,y']).krull_dimension()
+                0
+            """
+            return 0
 
         def is_field(self, proof=True):
             r"""

src/sage/misc/functional.py

@@ -23,6 +23,7 @@
 import math
 
 from sage.misc.lazy_import import lazy_import
+from sage.misc.superseded import deprecation
 
 lazy_import('sage.rings.complex_double', 'CDF')
 lazy_import('sage.rings.real_double', ['RDF', 'RealDoubleElement'])
@@ -918,16 +919,20 @@ def krull_dimension(x):
     EXAMPLES::
 
         sage: krull_dimension(QQ)
+        doctest:warning...:
+        DeprecationWarning: please use the krull_dimension method
+        See https://github.com/sagemath/sage/issues/39311 for details.
         0
-        sage: krull_dimension(ZZ)
+        sage: ZZ.krull_dimension()
         1
-        sage: krull_dimension(ZZ[sqrt(5)])                                              # needs sage.rings.number_field sage.symbolic
+        sage: ZZ[sqrt(5)].krull_dimension()                                              # needs sage.rings.number_field sage.symbolic
         1
         sage: U.<x,y,z> = PolynomialRing(ZZ, 3); U
         Multivariate Polynomial Ring in x, y, z over Integer Ring
         sage: U.krull_dimension()
         4
     """
+    deprecation(39311, "please use the krull_dimension method")
     return x.krull_dimension()
 
 

src/sage/rings/ring.pyx

@@ -826,54 +826,6 @@ cdef class CommutativeRing(Ring):
         except (NotImplementedError,TypeError):
             return coercion_model.division_parent(self)
 
-    def krull_dimension(self):
-        """
-        Return the Krull dimension of this commutative ring.
-
-        The Krull dimension is the length of the longest ascending chain
-        of prime ideals.
-
-        TESTS:
-
-        ``krull_dimension`` is not implemented for generic commutative
-        rings. Fields and PIDs, with Krull dimension equal to 0 and 1,
-        respectively, have naive implementations of ``krull_dimension``.
-        Orders in number fields also have Krull dimension 1::
-
-            sage: R = CommutativeRing(ZZ)
-            sage: R.krull_dimension()
-            Traceback (most recent call last):
-            ...
-            NotImplementedError
-            sage: QQ.krull_dimension()
-            0
-            sage: ZZ.krull_dimension()
-            1
-            sage: type(R); type(QQ); type(ZZ)
-            <class 'sage.rings.ring.CommutativeRing'>
-            <class 'sage.rings.rational_field.RationalField_with_category'>
-            <class 'sage.rings.integer_ring.IntegerRing_class'>
-
-        All orders in number fields have Krull dimension 1, including
-        non-maximal orders::
-
-            sage: # needs sage.rings.number_field
-            sage: K.<i> = QuadraticField(-1)
-            sage: R = K.maximal_order(); R
-            Gaussian Integers generated by i in Number Field in i
-             with defining polynomial x^2 + 1 with i = 1*I
-            sage: R.krull_dimension()
-            1
-            sage: R = K.order(2*i); R
-            Order of conductor 2 generated by 2*i in Number Field in i
-             with defining polynomial x^2 + 1 with i = 1*I
-            sage: R.is_maximal()
-            False
-            sage: R.krull_dimension()
-            1
-        """
-        raise NotImplementedError
-
     def extension(self, poly, name=None, names=None, **kwds):
         """
         Algebraically extend ``self`` by taking the quotient
@@ -1095,19 +1047,6 @@ cdef class Field(CommutativeRing):
         """
         return True
 
-    def krull_dimension(self):
-        """
-        Return the Krull dimension of this field, which is 0.
-
-        EXAMPLES::
-
-            sage: QQ.krull_dimension()
-            0
-            sage: Frac(QQ['x,y']).krull_dimension()
-            0
-        """
-        return 0
-
     def prime_subfield(self):
         """
         Return the prime subfield of ``self``.