Class NumberFieldIdeal

INPUT:
    field -- a number field
    x -- a list of NumberFieldElements belonging to the field

EXAMPLES:
    sage: NumberField(x^2 + 1, 'a').ideal(7)
    Fractional ideal (7)

Overrides: ideal.Ideal_generic.__init__

EXAMPLES:
    sage: K.<a> = NumberField(x^2 + 23)
    sage: K.ideal([2, 1/2*a - 1/2])._latex_()
    '\left(2, \frac{1}{2} a - \frac{1}{2}\right)'
    sage: latex(K.ideal([2, 1/2*a - 1/2]))
    \left(2, rac{1}{2} a - rac{1}{2}
ight)

Overrides: ideal.Ideal_generic._latex_

Compare an ideal of a number field to something else.

EXAMPLES:
    sage: K.<a> = NumberField(x^2 + 3); K
    Number Field in a with defining polynomial x^2 + 3
    sage: f = K.factor(15); f
    (Fractional ideal (1/2*a - 3/2))^2 * (Fractional ideal (5))
    sage: cmp(f[0][0], f[1][0])
    -1
    sage: cmp(f[0][0], f[0][0])
    0
    sage: cmp(f[1][0], f[0][0])
    1
    sage: f[1][0] == 5
    True
    sage: f[1][0] == GF(7)(5)
    False

Overrides: ideal.Ideal_generic.__cmp__

Return True if x is an element of this ideal.

This function is called (indirectly) when the \code{in}
operator is used.

EXAMPLES:
    sage: K.<a> = NumberField(x^2 + 23); K
    Number Field in a with defining polynomial x^2 + 23
    sage: I = K.factor(13)[0][0]; I
    Fractional ideal (13, a - 4)
    sage: I._contains_(a)
    False
    sage: a in I
    False
    sage: 13 in I
    True
    sage: 13/2 in I
    False
    sage: a + 9 in I
    True

    sage: K.<a> = NumberField(x^4 + 3); K
    Number Field in a with defining polynomial x^4 + 3
    sage: I = K.factor(13)[0][0]
    sage: I  # random sign in output
    Fractional ideal (-2*a^2 - 1)
    sage: 2/3 in I
    False
    sage: 1 in I
    False
    sage: 13 in I
    True
    sage: 1 in I*I^(-1)
    True
    sage: I   # random sign in output
    Fractional ideal (-2*a^2 - 1)

Overrides: ideal.Ideal_generic._contains_

File: sage/structure/sage_object.pyx (starting at line 86)

Overrides: ideal.Ideal_generic.__repr__

Returns PARI Hermite Normal Form representations of this
ideal.

EXAMPLES:
    sage: K.<w> = NumberField(x^2 + 23)
    sage: I = K.class_group().0.ideal(); I
    Fractional ideal (2, 1/2*w - 1/2)
    sage: I._pari_()
    [2, 0; 0, 1]

Overrides: structure.sage_object.SageObject._pari_

Returns self in PARI Hermite Normal Form as a string

EXAMPLES:
    sage: K.<w> = NumberField(x^2 + 23)
    sage: I = K.class_group().0.ideal()
    sage: I._pari_init_()
    '[2, 0; 0, 1]'

Overrides: structure.sage_object.SageObject._pari_init_

Return PARI's representation of this ideal in Hermite normal form.

EXAMPLES:
    sage: R.<x> = PolynomialRing(QQ)
    sage: K.<a> = NumberField(x^3 - 2)
    sage: I = K.ideal(2/(5+a))
    sage: I.pari_hnf()
    [2, 0, 50/127; 0, 2, 244/127; 0, 0, 2/127]

Return an immutable sequence of elements of this ideal (note:
their parent is the number field) that form a basis for this
ideal viewed as a ZZ-module.

OUTPUT:
    basis -- an immutable sequence.

EXAMPLES:
    sage: K.<z> = CyclotomicField(7)
    sage: I = K.factor(11)[0][0]
    sage: I.basis()           # warning -- choice of basis can be somewhat random
    [11, 11*z, 11*z^2, z^3 + 5*z^2 + 4*z + 10, z^4 + z^2 + z + 5, z^5 + z^4 + z^3 + 2*z^2 + 6*z + 5]

An example of a non-integral ideal.
    sage: J = 1/I
    sage: J          # warning -- choice of generators can be somewhat random 
    Fractional ideal (2/11*z^5 + 2/11*z^4 + 3/11*z^3 + 2/11)
    sage: J.basis()           # warning -- choice of basis can be somewhat random
    [1, z, z^2, 1/11*z^3 + 7/11*z^2 + 6/11*z + 10/11, 1/11*z^4 + 1/11*z^2 + 1/11*z + 7/11, 1/11*z^5 + 1/11*z^4 + 1/11*z^3 + 2/11*z^2 + 8/11*z + 7/11]

Return the free ZZ-module contained in the vector space
associated to the ambient number field, that corresponds
to this ideal.

EXAMPLES:
    sage: K.<z> = CyclotomicField(7)
    sage: I = K.factor(11)[0][0]; I
    Fractional ideal (-2*z^4 - 2*z^2 - 2*z + 1)
    sage: A = I.free_module()
    sage: A              # warning -- choice of basis can be somewhat random
    Free module of degree 6 and rank 6 over Integer Ring
    User basis matrix:
    [11  0  0  0  0  0]
    [ 0 11  0  0  0  0]
    [ 0  0 11  0  0  0]
    [10  4  5  1  0  0]
    [ 5  1  1  0  1  0]
    [ 5  6  2  1  1  1]

However, the actual ZZ-module is not at all random:
    sage: A.basis_matrix().change_ring(ZZ).echelon_form()
    [ 1  0  0  5  1  1]
    [ 0  1  0  1  1  7]
    [ 0  0  1  7  6 10]
    [ 0  0  0 11  0  0]
    [ 0  0  0  0 11  0]
    [ 0  0  0  0  0 11]

The ideal doesn't have to be integral:
    sage: J = I^(-1)
    sage: B = J.free_module()
    sage: B.echelonized_basis_matrix()
    [ 1/11     0     0  7/11  1/11  1/11]
    [    0  1/11     0  1/11  1/11  5/11]
    [    0     0  1/11  5/11  4/11 10/11]
    [    0     0     0     1     0     0]
    [    0     0     0     0     1     0]
    [    0     0     0     0     0     1]

This also works for relative extensions:
    sage: K.<a,b> = NumberField([x^2 + 1, x^2 + 2])
    sage: I = K.fractional_ideal(4)
    sage: I.free_module()
    Free module of degree 4 and rank 4 over Integer Ring
    User basis matrix:
    [  4   0   0   0]
    [ -3   7  -1   1]
    [  3   7   1   1]
    [  0 -10   0  -2]
    sage: J = I^(-1); J.free_module()
    Free module of degree 4 and rank 4 over Integer Ring
    User basis matrix:
    [  1/4     0     0     0]
    [-3/16  7/16 -1/16  1/16]
    [ 3/16  7/16  1/16  1/16]
    [    0  -5/8     0  -1/8]

An example of intersecting ideals by intersecting free modules.
    sage: K.<a> = NumberField(x^3 + x^2 - 2*x + 8)
    sage: I = K.factor(2)
    sage: p1 = I[0][0]; p2 = I[1][0]
    sage: N = p1.free_module().intersection(p2.free_module()); N
    Free module of degree 3 and rank 3 over Integer Ring
    Echelon basis matrix:
    [  1 1/2 1/2]
    [  0   1   1]
    [  0   0   2]
    sage: N.index_in(p1.free_module()).abs()
    2

Return a small ideal that is equivalent to self in the group
of fractional ideals modulo principal ideals.  Very often (but
not always) if self is principal then this function returns
the unit ideal.

ALGORITHM: Calls pari's idealred function.

EXAMPLES:
    sage: K.<w> = NumberField(x^2 + 23)
    sage: I = ideal(w*23^5); I
    Fractional ideal (6436343*w)
    sage: I.reduce_equiv()
    Fractional ideal (1)
    sage: I = K.class_group().0.ideal()^10; I
    Fractional ideal (1024, 1/2*w + 979/2)
    sage: I.reduce_equiv()
    Fractional ideal (2, 1/2*w - 1/2)

Express this ideal in terms of at most two generators, and one
if possible.

Note that if the ideal is not principal, then this uses PARI's
\code{idealtwoelt} function, which takes exponential time, the
first time it is called for each ideal.  Also, this indirectly
uses \code{bnfisprincipal}, so set \code{proof=True} if you
want to prove correctness (which \emph{is} the default).

EXAMPLE:
    sage: R.<x> = PolynomialRing(QQ)
    sage: K.<i> = NumberField(x^2+1, 'i')
    sage: J = K.ideal([i+1, 2])
    sage: J.gens()
    (i + 1, 2)
    sage: J.gens_reduced()
    (i + 1,)

TESTS:
    sage: all(j.parent() is K for j in J.gens())
    True
    sage: all(j.parent() is K for j in J.gens_reduced())
    True

    sage: K.<a> = NumberField(x^4 + 10*x^2 + 20)
    sage: J = K.prime_above(5)
    sage: J.is_principal()
    False
    sage: J.gens_reduced()
    (5, a)
    sage: all(j.parent() is K for j in J.gens())
    True
    sage: all(j.parent() is K for j in J.gens_reduced())
    True

Overrides: ideal.Ideal_generic.gens_reduced

Return a list of generators for this ideal as a $\mathbb{Z}$-module.

EXAMPLE:
    sage: R.<x> = PolynomialRing(QQ)        
    sage: K.<i> = NumberField(x^2 + 1)
    sage: J = K.ideal(i+1)
    sage: J.integral_basis()
    [2, i + 1]

Return a tuple (I, d), where I is an integral ideal, and d is the
smallest positive integer such that this ideal is equal to I/d.

EXAMPLE:
    sage: R.<x> = PolynomialRing(QQ)
    sage: K.<a> = NumberField(x^2-5)
    sage: I = K.ideal(2/(5+a))
    sage: I.is_integral()
    False
    sage: J,d = I.integral_split()
    sage: J
    Fractional ideal (-1/2*a + 5/2)
    sage: J.is_integral()
    True
    sage: d
    5
    sage: I == J/d
    True

Return True if this ideal is integral.

EXAMPLES:
   sage: R.<x> = PolynomialRing(QQ)        
   sage: K.<a> = NumberField(x^5-x+1)
   sage: K.ideal(a).is_integral()
   True
   sage: (K.ideal(1) / (3*a+1)).is_integral()
   False

Return True if this ideal is maximal.  This is equivalent to
self being prime and nonzero.

EXAMPLES:
    sage: K.<a> = NumberField(x^3 + 3); K
    Number Field in a with defining polynomial x^3 + 3
    sage: K.ideal(5).is_maximal()
    False
    sage: K.ideal(7).is_maximal()
    True        

Overrides: ideal.Ideal_generic.is_maximal

Return True if this ideal is prime.

EXAMPLES:
    sage: K.<a> = NumberField(x^2 - 17); K
    Number Field in a with defining polynomial x^2 - 17
    sage: K.ideal(5).is_prime()
    True
    sage: K.ideal(13).is_prime()
    False
    sage: K.ideal(17).is_prime()
    False        

Overrides: ideal.Ideal_generic.is_prime

Return True if this ideal is principal.

Since it uses the PARI method \code{bnfisprincipal}, specify
\code{proof=True} (this is the default setting) to prove the
correctness of the output.

EXAMPLES:
We create equal ideals in two different ways, and note that
they are both actually principal ideals. 
    sage: K = QuadraticField(-119,'a')
    sage: P = K.ideal([2]).factor()[1][0]
    sage: I = P^5
    sage: I.is_principal()
    True

Overrides: ideal.Ideal_generic.is_principal

Return True iff self is the zero ideal

EXAMPLES:
    sage: K.<a> = NumberField(x^2 + 2); K
    Number Field in a with defining polynomial x^2 + 2
    sage: K.ideal(3).is_zero()
    False
    sage: I=K.ideal(0); I.is_zero()
    True
    sage: I
    Ideal (0) of Number Field in a with defining polynomial x^2 + 2

    (0 is a NumberFieldIdeal, not a NumberFieldFractionIdeal)

Overrides: structure.element.Element.is_zero

Return the norm of this fractional ideal as a rational number.

EXAMPLES:
    sage: K.<a> = NumberField(x^4 + 23); K
    Number Field in a with defining polynomial x^4 + 23
    sage: I = K.ideal(19); I
    Fractional ideal (19)
    sage: factor(I.norm())
    19^4
    sage: F = I.factor()
    sage: F[0][0].norm().factor()
    19^2        

Return the number field that this is a fractional ideal in.

EXAMPLES:
    sage: K.<a> = NumberField(x^2 + 2); K
    Number Field in a with defining polynomial x^2 + 2
    sage: K.ideal(3).number_field()
    Number Field in a with defining polynomial x^2 + 2
    sage: K.ideal(0).number_field() # not tested (not implemented)
    Number Field in a with defining polynomial x^2 + 2        

Return the smallest nonnegative integer in $I \cap \mathbb{Z}$,
where $I$ is this ideal.  If $I = 0$, raise a ValueError.

EXAMPLE:
    sage: R.<x> = PolynomialRing(QQ)
    sage: K.<a> = NumberField(x^2+6)
    sage: I = K.ideal([4,a])/7
    sage: I.smallest_integer()
    2

Return the valuation of this fractional ideal at the prime
$\mathfrak{p}$.  If $\mathfrak{p}$ is not prime, raise a
ValueError.

INPUT:
    p -- a prime ideal of this number field.

OUTPUT:
    integer

EXAMPLES:
    sage: K.<a> = NumberField(x^5 + 2); K
    Number Field in a with defining polynomial x^5 + 2
    sage: i = K.ideal(38); i
    Fractional ideal (38)
    sage: i.valuation(K.factor(19)[0][0])
    1
    sage: i.valuation(K.factor(2)[0][0])
    5
    sage: i.valuation(K.factor(3)[0][0])
    0
    sage: i.valuation(0)
    Traceback (most recent call last):
    ...
    ValueError: p (= 0) must be nonzero