Class MPolynomialIdeal

Create an ideal in a multivariate polynomial ring.

INPUT:
    ring -- the ring the ideal is defined in
    gens -- a list of generators for the ideal
    coerce -- coerce elements to the ring \var{ring}?

EXAMPLES:
    sage: R.<x,y> = PolynomialRing(IntegerRing(), 2, order='lex')
    sage: R.ideal([x, y])
    Ideal (x, y) of Multivariate Polynomial Ring in x, y over Integer Ring
    sage: R.<x0,x1> = GF(3)[]
    sage: R.ideal([x0^2, x1^3])
    Ideal (x0^2, x1^3) of Multivariate Polynomial Ring in x0, x1 over Finite Field of size 3

Overrides: ideal.Ideal_generic.__init__

Return the Groebner fan of this ideal.

The base ring must be $\Q$ or a finite field $\F_p$ of with
$p <= 32749$.

EXAMPLES:
    sage: P.<x,y> = PolynomialRing(QQ)
    sage: i = ideal(x^2 - y^2 + 1)
    sage: g = i.groebner_fan()
    sage: g.reduced_groebner_bases()
    [[x^2 - y^2 + 1], [-x^2 + y^2 - 1]]

INPUT:
    is_groebner_basis -- bool (default False).  if True, then I.gens() must be
                         a Groebner basis with respect to the standard
                         degree lexicographic term order.
    symmetry -- default: None; if not None, describes symmetries of the ideal
    verbose -- default: False; if True, printout useful info during computations

Return the reduced Groebner basis of this ideal. A Groeber basis
$g_1,...,g_n$ for an ideal $I$ is a basis such that $<LT(g_i)>
= LT(I)$, i.e. the leading term ideal of $I$ is spanned by the
leading terms of $g_1,...,g_n$. Groebner bases are the key
concept in computational ideal theory in multivariate
polynomial rings which allows a variety of problems to be
solved. Additionally, a \emph{reduced} Groebner basis $G$ is a
unique representation for the ideal $<G>$ with respect to the
chosen monomial ordering.

INPUT:
    algorithm -- determines the algorithm to use, see below
                 for available algorithms.
    *args -- additional parameters passed to the respective
             implementations
    **kwds -- additional keyword parameters passed to the
              respective implementations

ALGORITHMS:
    \begin{description}
    \item[None] autoselect (default)
    \item['singular:groebner'] \Singular's \code{groebner} command
    \item['singular:std'] \Singular's \code{std} command
    \item['singular:stdhilb'] \Singular's \code{stdhib} command
    \item['singular:stdfglm'] \Singular's \code{stdfglm} command
    \item['singular:slimgb'] \Singular's \code{slimgb} command
    \item['libsingular:std'] lib\Singular's \code{std} command 
    \item['libsingular:slimgb'] lib\Singular's \code{slimgb} command
    \item['toy:buchberger'] \SAGE's toy/educational buchberger without strategy
    \item['toy:buchberger2'] \SAGE's toy/educational buchberger with strategy
    \item['macaulay2:gb'] Macaulay2's \code{gb} command (if available)
    \item['magma:GroebnerBasis'] \MAGMA's \code{Groebnerbasis} command (if available)
    \end{description}

NOTE: The \Singular and lib\Singular versions of the
respective algorithms are identically, but the former calls an
external \Singular process while the later calls a C function,
i.e. the calling overhead is smaller.

EXAMPLES:
    Consider Katsura-3 over QQ with lexicographical term
    ordering. We compute the reduced Groebner basis using every
    available implementation and check their equality.

    sage: P.<a,b,c> = PolynomialRing(QQ,3, order='lex')
    sage: I = sage.rings.ideal.Katsura(P,3) # regenerate to prevent caching
    sage: I.groebner_basis()
    [c^4 - 10/21*c^3 + 1/84*c^2 + 1/84*c, b + 30*c^3 - 79/7*c^2 + 3/7*c, a - 60*c^3 + 158/7*c^2 + 8/7*c - 1]

    sage: I = sage.rings.ideal.Katsura(P,3) # regenerate to prevent caching
    sage: I.groebner_basis('singular:groebner')
    [c^4 - 10/21*c^3 + 1/84*c^2 + 1/84*c, b + 30*c^3 - 79/7*c^2 + 3/7*c, a - 60*c^3 + 158/7*c^2 + 8/7*c - 1]

    sage: I = sage.rings.ideal.Katsura(P,3) # regenerate to prevent caching
    sage: I.groebner_basis('singular:std')
    [c^4 - 10/21*c^3 + 1/84*c^2 + 1/84*c, b + 30*c^3 - 79/7*c^2 + 3/7*c, a - 60*c^3 + 158/7*c^2 + 8/7*c - 1]

    sage: I = sage.rings.ideal.Katsura(P,3) # regenerate to prevent caching
    sage: I.groebner_basis('singular:stdhilb')
    [c^4 - 10/21*c^3 + 1/84*c^2 + 1/84*c, b + 30*c^3 - 79/7*c^2 + 3/7*c, a - 60*c^3 + 158/7*c^2 + 8/7*c - 1]

    sage: I = sage.rings.ideal.Katsura(P,3) # regenerate to prevent caching
    sage: I.groebner_basis('singular:stdfglm')
    [c^4 - 10/21*c^3 + 1/84*c^2 + 1/84*c, b + 30*c^3 - 79/7*c^2 + 3/7*c, a - 60*c^3 + 158/7*c^2 + 8/7*c - 1]

    sage: I = sage.rings.ideal.Katsura(P,3) # regenerate to prevent caching
    sage: I.groebner_basis('singular:slimgb')
    [c^4 - 10/21*c^3 + 1/84*c^2 + 1/84*c, b + 30*c^3 - 79/7*c^2 + 3/7*c, a - 60*c^3 + 158/7*c^2 + 8/7*c - 1]

Note that toy:buchberger does not return the reduced Groebner basis,

    sage: I = sage.rings.ideal.Katsura(P,3) # regenerate to prevent caching
    sage: I.groebner_basis('toy:buchberger')
    [a + 2*b + 2*c - 1, b^2 + 4/3*b*c - 1/3*b + c^2 - 1/3*c,
    a*b + b*c - 1/2*b, b + 30*c^3 - 79/7*c^2 + 3/7*c,
    a^2 - a + 2*b^2 + 2*c^2, b*c - 1/10*b + 6/5*c^2 - 2/5*c,
    c^4 - 10/21*c^3 + 1/84*c^2 + 1/84*c]

but that toy:buchberger2 does.

    sage: I = sage.rings.ideal.Katsura(P,3) # regenerate to prevent caching
    sage: I.groebner_basis('toy:buchberger2')
    [b + 30*c^3 - 79/7*c^2 + 3/7*c, c^4 - 10/21*c^3 + 1/84*c^2 + 1/84*c, a - 60*c^3 + 158/7*c^2 + 8/7*c - 1]

    sage: I = sage.rings.ideal.Katsura(P,3) # regenerate to prevent caching
    sage: I.groebner_basis('macaulay2:gb') # optional requires Macaulay2
    [84*c^4 - 40*c^3 + c^2 + c, 7*b + 210*c^3 - 79*c^2 + 3*c, 7*a - 420*c^3 + 158*c^2 + 8*c - 7]
    
    sage: I = sage.rings.ideal.Katsura(P,3) # regenerate to prevent caching
    sage: I.groebner_basis('magma:GroebnerBasis') # optional requires MAGMA
    [a - 60*c^3 + 158/7*c^2 + 8/7*c - 1, b + 30*c^3 - 79/7*c^2 + 3/7*c, c^4 - 10/21*c^3 + 1/84*c^2 + 1/84*c]

    If Macaulay2 is installed, Groebner bases over $\ZZ$ can be computed.

    sage: P.<a,b,c> = PolynomialRing(ZZ,3)
    sage: I = P * (a + 2*b + 2*c - 1, a^2 - a + 2*b^2 + 2*c^2, 2*a*b + 2*b*c - b)
    sage: I.groebner_basis() #optional requires Macaulay2 
    [a + 2*b + 2*c - 1, 10*b*c + 12*c^2 - b - 4*c, 2*b^2 - 4*b*c - 6*c^2 + 2*c, 
     42*c^3 + b^2 + 2*b*c - 14*c^2 + b, 2*b*c^2 - 6*c^3 + b^2 + 5*b*c + 8*c^2 - b - 2*c,
     b^3 + b*c^2 + 12*c^3 + b^2 + b*c - 4*c^2]

    \SAGE also supports local orderings:

    sage: P.<x,y,z> = PolynomialRing(QQ,3,order='negdegrevlex')
    sage: I = P * (  x*y*z + z^5, 2*x^2 + y^3 + z^7, 3*z^5 +y ^5 )
    sage: I.groebner_basis()
    [x^2 + 1/2*y^3, x*y*z + z^5, y^5 + 3*z^5, y^4*z - 2*x*z^5, z^6]

ALGORITHM: Uses \Singular, \MAGMA (if available), Macaulay2 (if
available), or toy implementation.

Return the ideal \var{I} in \var{P} spanned by the generators
$g_1, ..., g_n$ of self as returned by \code{self.gens()}.

INPUT:
    P -- a multivariate polynomial ring

EXAMPLE:
   sage: P.<x,y,z> = PolynomialRing(QQ,3,order='lex')
   sage: I = sage.rings.ideal.Cyclic(P)
   sage: I
   Ideal (x + y + z, x*y + x*z + y*z, x*y*z - 1) of
   Multivariate Polynomial Ring in x, y, z over Rational Field

   sage: I.groebner_basis()
   [z^3 - 1, y^2 + y*z + z^2, x + y + z]

   sage: Q.<x,y,z> = P.change_ring(order='degrevlex'); Q
   Multivariate Polynomial Ring in x, y, z over Rational Field
   sage: Q.term_order()
   Degree reverse lexicographic term order

   sage: J = I.change_ring(Q); J
   Ideal (x + y + z, x*y + x*z + y*z, x*y*z - 1) of
   Multivariate Polynomial Ring in x, y, z over Rational Field

   sage: J.groebner_basis()
   [x + y + z, y^2 + y*z + z^2, z^3 - 1]

Reduce an element modulo the reduced Groebner basis for this
ideal. This returns 0 if and only if the element is in this
ideal. In any case, this reduction is unique up to monomial
orders.

EXAMPLES:
    sage: R.<x,y> = PolynomialRing(QQ, 2)
    sage: I = (x^3 + y, y)*R
    sage: I.reduce(y)
    0
    sage: I.reduce(x^3)
    0
    sage: I.reduce(x - y)
    x

    sage: I = (y^2 - (x^3 + x))*R
    sage: I.reduce(x^3)
    y^2 - x
    sage: I.reduce(x^6)
    y^4 - 2*x*y^2 + x^2
    sage: (y^2 - x)^2
    y^4 - 2*x*y^2 + x^2

NOTE: Requires computation of a Groebner basis, which can be a
very expensive operation.

Overrides: ideal.Ideal_generic.reduce

Return homogeneous ideal spanned by the homogeneous
polynomials generated by homogenizing the generators of this
ideal.

INPUT:
    h -- variable name or variable in cover ring (default: 'h')

EXAMPLE:
    sage: P.<x,y,z> = PolynomialRing(GF(2))
    sage: I = Ideal([x^2*y + z + 1, x + y^2 + 1]); I
    Ideal (x^2*y + z + 1, y^2 + x + 1) of Multivariate
    Polynomial Ring in x, y, z over Finite Field of size 2

    sage: I.homogenize()
    Ideal (x^2*y + z*h^2 + h^3, y^2 + x*h + h^2) of
    Multivariate Polynomial Ring in x, y, z, h over Finite
    Field of size 2

    sage: I.homogenize(y)
    Ideal (x^2*y + y^3 + y^2*z, x*y) of Multivariate
    Polynomial Ring in x, y, z over Finite Field of size 2


   sage: I = Ideal([x^2*y + z^3 + y^2*x, x + y^2 + 1])
   sage: I.homogenize()
   Ideal (x^2*y + x*y^2 + z^3, y^2 + x*h + h^2) of
   Multivariate Polynomial Ring in x, y, z, h over Finite
   Field of size 2

Return \code{True} if this ideal is spanned by homogeneous
polynomials, i.e. if it is a homogeneous ideal.

EXAMPLE:
    sage: P.<x,y,z> = PolynomialRing(QQ,3)
    sage: I = sage.rings.ideal.Katsura(P)
    sage: I
    Ideal (x + 2*y + 2*z - 1, x^2 + 2*y^2 + 2*z^2 - x, 2*x*y +
    2*y*z - y) of Multivariate Polynomial Ring in x, y, z over
    Rational Field

    sage: I.is_homogeneous()
    False

    sage: J = I.homogenize()
    sage: J
    Ideal (x + 2*y + 2*z - h, x^2 + 2*y^2 + 2*z^2 - x*h, 2*x*y
    + 2*y*z - y*h) of Multivariate Polynomial Ring in x, y, z,
    h over Rational Field

    sage: J.is_homogeneous()
    True

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.

INPUT: 
    algorithm - defaults to use libsingular, if it is anything else
                we will use the kbase() command

EXAMPLES:
    sage: R.<x,y,z> = PolynomialRing(QQ)
    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: I.normal_basis(algorithm='singular')
    [y*z^2, z^2, y*z, z, x*y, y, x, 1]