Module ideal

Create the ideal in ring with given generators.

There are some shorthand notations for creating an ideal, in
addition to use the Ideal function:

\begin{verbatim}
    --  R.ideal(gens, coerce=True)
    --  gens*R
    --  R*gens
\end{verbatim}        

INPUT:
    R -- a ring
    gens -- list of elements
    coerce -- bool (default: True); whether gens need to be coerced into ring.

Alternatively, one can also call this function with the syntax
     Ideal(gens)
where gens is a nonempty list of generators or a single generator.
    
OUTPUT:
    The ideal of ring generated by gens.

EXAMPLES:
    sage: R, x = PolynomialRing(ZZ, 'x').objgen()
    sage: I = R.ideal([4 + 3*x + x^2, 1 + x^2])
    sage: I
    Ideal (x^2 + 3*x + 4, x^2 + 1) of Univariate Polynomial Ring in x over Integer Ring
    sage: Ideal(R, [4 + 3*x + x^2, 1 + x^2])
    Ideal (x^2 + 3*x + 4, x^2 + 1) of Univariate Polynomial Ring in x over Integer Ring
    sage: Ideal((4 + 3*x + x^2, 1 + x^2))
    Ideal (x^2 + 3*x + 4, x^2 + 1) of Univariate Polynomial Ring in x over Integer Ring
    
    sage: ideal(x^2-2*x+1, x^2-1)
    Ideal (x^2 - 1, x^2 - 2*x + 1) of Univariate Polynomial Ring in x over Integer Ring
    sage: ideal([x^2-2*x+1, x^2-1])
    Ideal (x^2 - 1, x^2 - 2*x + 1) of Univariate Polynomial Ring in x over Integer Ring
    sage: l = [x^2-2*x+1, x^2-1]
    sage: ideal(f^2 for f in l)
    Ideal (x^4 - 4*x^3 + 6*x^2 - 4*x + 1, x^4 - 2*x^2 + 1) of
    Univariate Polynomial Ring in x over Integer Ring

This example illustrates how \SAGE finds a common ambient ring for
the ideal, even though 1 is in the integers (in this case).

    sage: R.<t> = ZZ['t']
    sage: i = ideal(1,t,t^2)
    sage: i
    Ideal (t^2, 1, t) of Univariate Polynomial Ring in t over Integer Ring
    sage: ideal(1/2,t,t^2)
    Principal ideal (1) of Univariate Polynomial Ring in t over Rational Field

TESTS:
    sage: R, x = PolynomialRing(ZZ, 'x').objgen()
    sage: I = R.ideal([4 + 3*x + x^2, 1 + x^2])
    sage: I == loads(dumps(I))
    True

    sage: I = Ideal(R, [4 + 3*x + x^2, 1 + x^2])
    sage: I == loads(dumps(I))
    True
            
    sage: I = Ideal((4 + 3*x + x^2, 1 + x^2))
    sage: I == loads(dumps(I))
    True

Returns True if object is an ideal of a ring.

EXAMPLES:
A simple example involving the ring of integers. Note that SAGE does
not interpret rings objects themselves as ideals. However, one can
still explicitly construct these ideals:
    sage: R = ZZ
    sage: is_Ideal(R)
    False
    sage: 1*R; is_Ideal(1*R)
    Principal ideal (1) of Integer Ring
    True
    sage: 0*R; is_Ideal(0*R)
    Principal ideal (0) of Integer Ring
    True

Sage recognizes ideals of polynomial rings as well:
    sage: R = PolynomialRing(QQ, 'x'); x = R.gen()
    sage: I = R.ideal(x^2 + 1); I
    Principal ideal (x^2 + 1) of Univariate Polynomial Ring in x over Rational Field
    sage: is_Ideal(I)
    True
    sage: is_Ideal((x^2 + 1)*R)
    True

    Ideal of cyclic n-roots from 1-st n variables of R if R is
    coercable to Singular. If n==None n is set to R.ngens()

    INPUT:
        R -- base ring to construct ideal for
        n -- number of cyclic roots (default: None)
        homog -- if True a homogenous ideal is returned using the last
                 variable in the ideal (default: False)
        singular -- singular instance to use

    
ote{R will be set as the active ring in Singular}

    EXAMPLES:
    An example from a multivariate polynomial ring over the rationals:
        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]
        
    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
    

n-th katsura ideal of R if R is coercable to Singular.  If n==None
n is set to R.ngens()

INPUT:
    R -- base ring to construct ideal for
    n -- which katsura ideal of R
    homog -- if True a homogenous ideal is returned using the last
             variable in the ideal (default: False)
    singular -- singular instance to use

EXAMPLES:
    sage: P.<x,y,z> = PolynomialRing(QQ,3)
    sage: I = sage.rings.ideal.Katsura(P,3); 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: Q.<x> = PolynomialRing(QQ,1)
    sage: J = sage.rings.ideal.Katsura(Q,1); J
    Ideal (x - 1) of Multivariate Polynomial Ring in x over Rational Field

Let q = R.base_ring().order() and (x0,...,x_n) = R.gens() then if
q is finite this constructor returns

$< x_0^q - x_0, ... , x_n^q - x_n >.$

We call this ideal the field ideal and the generators the field
equations.

EXAMPLES:
The Field Ideal generated from the polynomial ring over two variables
in the finite field of size 2:
    sage: P.<x,y> = PolynomialRing(GF(2),2)
    sage: I = sage.rings.ideal.FieldIdeal(P); I
    Ideal (x^2 + x, y^2 + y) of Multivariate Polynomial Ring in x, y over
    Finite Field of size 2

Antoher, similar example:
    sage: Q.<x1,x2,x3,x4> = PolynomialRing(GF(2^4,name='alpha'), 4)
    sage: J = sage.rings.ideal.FieldIdeal(Q); J
    Ideal (x1^16 + x1, x2^16 + x2, x3^16 + x3, x4^16 + x4) of
    Multivariate Polynomial Ring in x1, x2, x3, x4 over Finite
    Field in alpha of size 2^4