Module multi_polynomial_ideal

Ideals in multivariate polynomial rings.

\SAGE has a powerful system to compute with multivariate polynomial
rings. Most algorithms dealing with these ideals are centered the
computation of \emph{Groebner base}. \SAGE makes use of \Singular to
implement this functionality. \Singular is widely regarded as the best
open-source system for Groebner basis calculation in multivariate
polynomial rings over fields.

AUTHORS:
    -- William Stein
    -- Kiran S. Kedlaya (2006-02-12): added Macaulay2 analogues of
              some \Singular features
    -- Martin Albrecht

EXAMPLES:

We compute a Groebner basis for some given ideal. The type returned by
the \code{groebner_basis} method is \code{Sequence}, i.e. it is not an
\code{MPolynomialIdeal}.

    sage: x,y,z = QQ['x,y,z'].gens()
    sage: I = ideal(x^5 + y^4 + z^3 - 1,  x^3 + y^3 + z^2 - 1)
    sage: B = I.groebner_basis()
    sage: type(B)
    <class 'sage.structure.sequence.Sequence'>
    
Groebner bases can be used to solve the ideal membership problem.
    sage: f,g,h = B
    sage: (2*x*f + g).reduce(B)
    0

    sage: (2*x*f + g) in I
    True

    sage: (2*x*f + 2*z*h + y^3).reduce(B)
    y^3

    sage: (2*x*f + 2*z*h + y^3) in I
    False
    
We compute a Groebner basis for cyclic 6, which is a standard
benchmark and test ideal.
    sage: R.<x,y,z,t,u,v> = QQ['x,y,z,t,u,v']
    sage: I = sage.rings.ideal.Cyclic(R,6)
    sage: B = I.groebner_basis()
    sage: len(B)
    45

We compute in a quotient of a polynomial ring over $\ZZ/17\ZZ$:
    sage: R.<x,y> = ZZ[]
    sage: S.<a,b> = R.quotient((x^2 + y^2, 17)) # optional -- requires Macaulay2
    sage: S                                     # optional
    Quotient of Multivariate Polynomial Ring in x, y over Integer Ring
    by the ideal (x^2 + y^2, 17)

    sage: a^2 + b^2 == 0                        # optional 
    True
    sage: a^3 - b^2                             # optional
    -1*a*b^2 - b^2
    sage: (a+b)^17                              # optional
    a*b^16 + b^17
    sage: S(17) == 0                            # optional
    True

Working with a polynomial ring over $\ZZ$:
    sage: R.<x,y,z,w> = ZZ['x,y,z,w']             
    sage: i = ideal(x^2 + y^2 - z^2 - w^2, x-y)
    sage: j = i^2
    sage: j.groebner_basis()                    # optional
    [x^2 - 2*x*y + y^2, 2*x*y^2 - 2*y^3 - x*z^2 + y*z^2 - x*w^2 +
    y*w^2, 4*y^4 - 4*y^2*z^2 + z^4 - 4*y^2*w^2 + 2*z^2*w^2 + w^4]

    sage: y^2 - 2*x*y + x^2 in j                # optional
    True
    sage: 0 in j                                # optional
    True

We do a Groebner basis computation over a number field:
    sage: K.<zeta> = CyclotomicField(3)
    sage: R.<x,y,z> = K[]; R
    Multivariate Polynomial Ring in x, y, z over Cyclotomic Field of order 3 and degree 2

    sage: i = ideal(x - zeta*y + 1, x^3 - zeta*y^3); i
    Ideal (x + (-zeta)*y + 1, x^3 + (-zeta)*y^3) of Multivariate
    Polynomial Ring in x, y, z over Cyclotomic Field of order 3 and degree 2

    sage: i.groebner_basis()
    [x + (-zeta)*y + 1, y^3 + (2*zeta + 1)*y^2 + (zeta - 1)*y - 1/3*zeta - 2/3]

    sage: S = R.quotient(i); S
    Quotient of Multivariate Polynomial Ring in x, y, z over
    Cyclotomic Field of order 3 and degree 2 by the ideal (x +
    (-zeta)*y + 1, x^3 + (-zeta)*y^3)

    sage: S.0  - zeta*S.1
    -1
    sage: S.0^3 - zeta*S.1^3
    0

Two examples from the Mathematica documentation (done in \SAGE):
    We compute a Groebner basis:
        sage: R.<x,y> = PolynomialRing(QQ, order='lex')
        sage: ideal(x^2 - 2*y^2, x*y - 3).groebner_basis()
        [y^4 - 9/2, x - 2/3*y^3]

    We show that three polynomials have no common root:
        sage: R.<x,y> = QQ[]
        sage: ideal(x+y, x^2 - 1, y^2 - 2*x).groebner_basis()
        [1]

TESTS:
    sage: x,y,z = QQ['x,y,z'].gens()
    sage: I = ideal(x^5 + y^4 + z^3 - 1,  x^3 + y^3 + z^2 - 1)
    sage: I == loads(dumps(I))
    True

Return \code{True} if the provided argument \var{x} is an ideal in
the multivariate polynomial ring.

INPUT:
    x -- an arbitrary object

EXAMPLE:
    sage: P.<x,y,z> = PolynomialRing(QQ)
    sage: I = [x + 2*y + 2*z - 1, x^2 + 2*y^2 + 2*z^2 - x, 2*x*y + 2*y*z - y]

\SAGE distinguishes between a list of generators for an ideal and
the ideal itself. This distinction is inconsisten with \Singular
but matches \Magma's behavior.

    sage: is_MPolynomialIdeal(I)
    False

    sage: I = Ideal(I)
    sage: is_MPolynomialIdeal(I)
    True

Decorator to force a reduced \Singular groebner basis.

NOTE: This decorator is used automatically internally so the user
does not need to use it manually.