Trac #29543: normal_basis for positive-dimensional ideals

This ticket adds a `degree` option to the `normal_basis` method of
ideals.

This allows to limit the output to monomials of a particular degree,
which is useful when the corresponding quotient ring is not finite-
dimensional as a vector space.

{{{
sage: R.<x,y,z> = QQ[]
sage: I = R.ideal(x^2 + y^2 - 1)
sage: [I.normal_basis(d) for d in (0..3)]
[[1],
 [z, y, x],
 [z^2, y*z, x*z, y^2, x*y],
 [z^3, y*z^2, x*z^2, y^2*z, x*y*z, y^3, x*y^2]]
}}}

Previously, the method could only be used when the quotient ring was
finite-dimensional.

This functionality is provided by Singular. For reference, the
corresponding Singular function is [https://www.singular.uni-
kl.de/Manual/4-1-2/sing_275.htm#SEC315 kbase].

URL: https://trac.sagemath.org/29543
Reported by: gh-mwageringel
Ticket author(s): Markus Wageringel
Reviewer(s): Travis Scrimshaw, Kwankyu Lee

Author: Release Manager

src/sage/rings/polynomial/multi_polynomial_ideal.py

@@ -2888,38 +2888,70 @@ def hilbert_numerator(self, grading = None, algorithm = 'sage'):
             raise ValueError("'algorithm' must be one of 'sage' or 'singular'")
 
     @require_field
-    def _normal_basis_libsingular(self):
+    def _normal_basis_libsingular(self, degree):
         r"""
-        Returns the normal basis for a given groebner basis. It will use
-        the Groebner Basis as computed by
+        Return the normal basis for a given Groebner basis.
+
+        This will use the Groebner basis as computed by
         ``MPolynomialIdeal._groebner_basis_libsingular()``.
 
+        INPUT:
+
+        - ``degree`` -- ``None`` or integer
+
+        OUTPUT:
+
+        If ``degree`` is an integer, only the monomials of the given degree in
+        the normal basis.
+
         EXAMPLES::
 
             sage: R.<x,y,z> = PolynomialRing(QQ)
             sage: I = R.ideal(x^2-2*x*z+5, x*y^2+y*z+1, 3*y^2-8*x*z)
             sage: I.normal_basis() #indirect doctest
             [z^2, y*z, x*z, z, x*y, y, x, 1]
+            sage: J = R.ideal(x^2-2*x*z+5)
+            sage: J.normal_basis(3)  # indirect doctest
+            [z^3, y*z^2, x*z^2, y^2*z, x*y*z, y^3, x*y^2]
+
+        TESTS:
+
+        Check that zero is not included in trivial results::
+
+            sage: R.<x,y,z> = PolynomialRing(QQ)
+            sage: I = R.ideal(x^2-2*x*z+5, x*y^2+y*z+1, 3*y^2-8*x*z)
+            sage: I._normal_basis_libsingular(5)
+            []
         """
         from sage.rings.polynomial.multi_polynomial_ideal_libsingular import kbase_libsingular
         from sage.rings.polynomial.multi_polynomial_sequence import PolynomialSequence
         gb = self._groebner_basis_libsingular()
-
-        return PolynomialSequence(self.ring(), kbase_libsingular(self.ring().ideal(gb)), immutable=True)
+        res = kbase_libsingular(self.ring().ideal(gb), degree)
+        if len(res) == 1 and res[0].is_zero():
+            res = []
+        return PolynomialSequence(self.ring(), res, immutable=True)
 
     @require_field
     @handle_AA_and_QQbar
-    def normal_basis(self, algorithm='libsingular', singular=singular_default):
+    def normal_basis(self, degree=None, algorithm='libsingular',
+                     singular=singular_default):
         """
-        Returns a vector space basis (consisting of monomials) of the
-        quotient ring by the ideal, resp. of a free module by the module,
-        in case it is finite dimensional and if the input is a standard
-        basis with respect to the ring ordering.
+        Return a vector space basis of the quotient ring of this ideal.
 
         INPUT:
 
-        ``algorithm`` - defaults to use libsingular, if it is anything
-        else we will use the ``kbase()`` command
+        - ``degree`` -- integer (default: ``None``)
+
+        - ``algorithm`` -- string (default: ``"libsingular"``); if not the
+          default, this will use the ``kbase()`` command from Singular
+
+        - ``singular`` -- the singular interpreter to use when ``algorithm`` is
+          not ``"libsingular"`` (default: the default instance)
+
+        OUTPUT:
+
+        Monomials in the basis. If ``degree`` is given, only the monomials of
+        the given degree are returned.
 
         EXAMPLES::
 
@@ -2930,6 +2962,18 @@ def normal_basis(self, algorithm='libsingular', singular=singular_default):
             sage: I.normal_basis(algorithm='singular')
             [y*z^2, z^2, y*z, z, x*y, y, x, 1]
 
+        The result can be restricted to monomials of a chosen degree, which is
+        particularly useful when the quotient ring is not finite-dimensional as
+        a vector space.  ::
+
+            sage: J = R.ideal(x^2+y^2+z^2-4, x^2+2*y^2-5)
+            sage: J.dimension()
+            1
+            sage: [J.normal_basis(d) for d in (0..3)]
+            [[1], [z, y, x], [z^2, y*z, x*z, x*y], [z^3, y*z^2, x*z^2, x*y*z]]
+            sage: [J.normal_basis(d, algorithm='singular') for d in (0..3)]
+            [[1], [z, y, x], [z^2, y*z, x*z, x*y], [z^3, y*z^2, x*z^2, x*y*z]]
+
         TESTS:
 
         Check that this method works over QQbar (:trac:`25351`)::
@@ -2938,15 +2982,35 @@ def normal_basis(self, algorithm='libsingular', singular=singular_default):
             sage: I = R.ideal(x^2+y^2+z^2-4, x^2+2*y^2-5, x*z-1)
             sage: I.normal_basis()
             [y*z^2, z^2, y*z, z, x*y, y, x, 1]
+            sage: J = R.ideal(x^2+y^2+z^2-4, x^2+2*y^2-5)
+            sage: [J.normal_basis(d) for d in (0..3)]
+            [[1], [z, y, x], [z^2, y*z, x*z, x*y], [z^3, y*z^2, x*z^2, x*y*z]]
+
+        Check the deprecation::
+
+            sage: R.<x,y> = PolynomialRing(QQ)
+            sage: _ = R.ideal(x^2+y^2, x*y+2*y).normal_basis('singular')
+            doctest:...: DeprecationWarning: "algorithm" should be used as keyword argument
+            See https://trac.sagemath.org/29543 for details.
         """
         from sage.rings.polynomial.multi_polynomial_sequence import PolynomialSequence
+        if isinstance(degree, str):
+            from sage.misc.superseded import deprecation
+            deprecation(29543,
+                        '"algorithm" should be used as keyword argument')
+            algorithm = degree
+            degree = None
 
         if algorithm == 'libsingular':
-            return self._normal_basis_libsingular()
+            return self._normal_basis_libsingular(degree)
         else:
             gb = self.groebner_basis()
             R = self.ring()
-            return PolynomialSequence(R, [R(f) for f in singular.kbase(R.ideal(gb))], immutable=True)
+            if degree is None:
+                res = singular.kbase(R.ideal(gb))
+            else:
+                res = singular.kbase(R.ideal(gb), int(degree))
+            return PolynomialSequence(R, [R(f) for f in res], immutable=True)
 
 
 class MPolynomialIdeal_macaulay2_repr:

src/sage/rings/polynomial/multi_polynomial_ideal_libsingular.pyx

@@ -146,14 +146,17 @@ cdef ideal *sage_ideal_to_singular_ideal(I) except NULL:
             raise TypeError("All generators must be of type MPolynomial_libsingular.")
     return i
 
-def kbase_libsingular(I):
+def kbase_libsingular(I, degree=None):
     """
     SINGULAR's ``kbase()`` algorithm.
 
     INPUT:
 
     - ``I`` -- a groebner basis of an ideal
 
+    - ``degree`` -- integer (default: ``None``); if not ``None``, return
+      only the monomials of the given degree
+
     OUTPUT:
 
     Computes a vector space basis (consisting of monomials) of the quotient
@@ -162,12 +165,19 @@ def kbase_libsingular(I):
     the ring ordering. If the input is not a standard basis, the leading terms
     of the input are used and the result may have no meaning.
 
+    With two arguments: computes the part of a vector space basis of the
+    respective quotient with degree of the monomials equal to the second
+    argument. Here, the quotient does not need to be finite dimensional.
+
     EXAMPLES::
 
         sage: R.<x,y> = PolynomialRing(QQ, order='lex')
         sage: I = R.ideal(x^2-2*y^2, x*y-3)
-        sage: I.normal_basis()
+        sage: I.normal_basis()  # indirect doctest
         [y^3, y^2, y, 1]
+        sage: J = R.ideal(x^2-2*y^2)
+        sage: [J.normal_basis(d) for d in (0..4)]  # indirect doctest
+        [[1], [y, x], [y^2, x*y], [y^3, x*y^2], [y^4, x*y^3]]
     """
 
     global singular_options
@@ -179,8 +189,10 @@ def kbase_libsingular(I):
     cdef ideal *result
     singular_options = singular_options | Sy_bit(OPT_REDSB)
 
+    degree = -1 if degree is None else int(degree)
+
     sig_on()
-    result = scKBase(-1, i, q)
+    result = scKBase(degree, i, q)
     sig_off()
 
     id_Delete(&i, r)