# Element operations

## Creation

genMethod
gen(L::SimpleNumField) -> NumFieldElem

Given a simple number field $L = K[x]/(x)$ over $K$, this functions returns the class of $x$, which is the canonical primitive element of $L$ over $K$.

gensMethod
gens(L::NonSimpleNumField) -> Vector{NumFieldElem}

Given a non-simple number field $L = K[x_1,\dotsc,x_n]/(f_1,\dotsc,f_n)$ over $K$, this functions returns the list $\bar x_1,\dotsc,\bar x_n$.

Elements can also be created by specifying the coordinates with respect to the basis of the number field:

    (L::NumberField)(c::Vector{NumFieldElem}) -> NumFieldElem

Given a number field $L/K$ of degree $d$ and a vector c length $d$, this constructs the element a with coordinates(a) == c.

julia> Qx, x = QQ["x"];

julia> K, a = NumberField(x^2 - 2, "a");

julia> K([1, 2])
2*a + 1

julia> L, b = radical_extension(3, a, "b")
(Relative number field with defining polynomial x^3 - a
over Number field over Rational Field with defining polynomial x^2 - 2, b)

julia> L([a, 1, 1//2])
1//2*b^2 + b + a
quadratic_defectMethod
quadratic_defect(a::Union{NumFieldElem,Rational,fmpq}, p) -> Union{Inf, PosInf}

Returns the valuation of the quadratic defect of the element $a$ at $p$, which can either be prime object or an infinite place of the parent of $a$.

hilbert_symbolMethod
hilbert_symbol(a::NumFieldElem, b::NumFieldElem, p::NfOrdIdl) -> Int

Returns the local Hilbert symbol $(a,b)_p$.

representation_matrixMethod
representation_matrix(a::NumFieldElem) -> MatElem

Returns the representation matrix of $a$, that is, the matrix representing multiplication with $a$ with respect to the canonical basis of the parent of $a$.

basis_matrixMethod
basis_matrix(v::Vector{NumFieldElem}) -> Mat

Given a vector $v$ of $n$ elements of a number field $K$ of degree $d$, this function returns an $n x d$ matrix with entries in the base field of $K$, where row $i$ contains the coefficients of $v[i]$ with respect of the canonical basis of $K$.

coefficientsMethod
coefficients(a::SimpleNumFieldElem, i::Int) -> Vector{FieldElem}

Given a number field element a of a simple number field extension L/K, this function returns the coefficients of a, when expanded in the canonical power basis of L.

coordinatesMethod
coordinates(x::NumFieldElem{T}) -> Vector{T}

Given an element $x$ in a number field $K$, this function returns the coordinates of $x$ with respect to the basis of $K$ (the output of the 'basis' function).

absolute_coordinatesMethod
absolute_coordinates(x::NumFieldElem{T}) -> Vector{T}

Given an element $x$ in a number field $K$, this function returns the coordinates of $x$ with respect to the basis of $K$ over the rationals (the output of the 'absolute_basis' function).

coeffMethod
coeff(a::SimpleNumFieldElem, i::Int) -> FieldElem

Given a number field element a of a simple number field extension L/K, this function returns the i-th coefficient of a, when expanded in the canonical power basis of L. The result is an element of K.

valuationMethod
valuation(a::NumFieldElem, p::NfOrdIdl) -> fmpz

Computes the $\mathfrak p$-adic valuation of $a$, that is, the largest $i$ such that $a$ is contained in $\mathfrak p^i$.

torsion_unit_orderMethod
torsion_unit_order(x::nf_elem, n::Int)

Given a torsion unit $x$ together with a multiple $n$ of its order, compute the order of $x$, that is, the smallest $k \in \mathbb Z_{\geq 1}$ such that $x^k = 1$.

It is not checked whether $x$ is a torsion unit.

trMethod
tr(a::NumFieldElem) -> NumFieldElem

Returns the trace of an element $a$ of a number field extension $L/K$. This will be an element of $K$.

absolute_trMethod
absolute_tr(a::NumFieldElem) -> fmpq

Given a number field element $a$, returns the absolute trace of $a$.

algebraic_splitMethod
algebraic_split(a::nf_elem) -> nf_elem, nf_elem

Writes the input as a quotient of two "small" algebraic integers.

### Conjugates

conjugatesMethod
conjugates(x::nf_elem, C::AcbField) -> Vector{acb}

Compute the conjugates of $x$ as elements of type acb. Recall that we order the complex conjugates $\sigma_{r+1}(x),...,\sigma_{r+2s}(x)$ such that $\sigma_{i}(x) = \overline{sigma_{i + s}(x)}$ for $r + 1 \leq i \leq r + s$.

Let p be the precision of C, then every entry $y$ of the vector returned satisfies radius(real(y)) < 2^-p and radius(imag(y)) < 2^-p respectively.

conjugatesMethod
conjugates(x::nf_elem, abs_tol::Int) -> Vector{acb}

Compute the conjugates of $x$ as elements of type acb. Recall that we order the complex conjugates $\sigma_{r+1}(x),...,\sigma_{r+2s}(x)$ such that $\sigma_{i}(x) = \overline{sigma_{i + s}(x)}$ for $r + 1 \leq i \leq r + s$.

Every entry $y$ of the vector returned satisfies radius(real(y)) < 2^-abs_tol and radius(imag(y)) < 2^-abs_tol respectively.

conjugates_logMethod
conjugates_arb_log(x::nf_elem, abs_tol::Int) -> Vector{arb}

Returns the elements $(\log(\lvert \sigma_1(x) \rvert),\dotsc,\log(\lvert\sigma_r(x) \rvert), \dotsc,2\log(\lvert \sigma_{r+1}(x) \rvert),\dotsc, 2\log(\lvert \sigma_{r+s}(x)\rvert))$ as elements of type arb with radius less then 2^-abs_tol.

conjugates_realMethod
conjugates_arb_real(x::nf_elem, abs_tol::Int) -> Vector{arb}

Compute the real conjugates of $x$ as elements of type arb.

Every entry $y$ of the array returned satisfies radius(y) < 2^-abs_tol.

conjugates_complexMethod
conjugates_complex(x::nf_elem, abs_tol::Int) -> Vector{acb}

Compute the complex conjugates of $x$ as elements of type acb. Recall that we order the complex conjugates $\sigma_{r+1}(x),...,\sigma_{r+2s}(x)$ such that $\sigma_{i}(x) = \overline{sigma_{i + s}(x)}$ for $r + 1 \leq i \leq r + s$.

Every entry $y$ of the array returned satisfies radius(real(y)) < 2^-abs_tol and radius(imag(y)) < 2^-abs_tol.

conjugates_arb_log_normaliseMethod
conjugates_arb_log_normalise(x::nf_elem, p::Int = 10)
conjugates_arb_log_normalise(x::FacElem{nf_elem, AnticNumberField}, p::Int = 10)

The "normalised" logarithms, i.e. the array $c_i\log |x^{(i)}| - 1/n\log|N(x)|$, so the (weighted) sum adds up to zero.

minkowski_mapMethod
minkowski_map(a::nf_elem, abs_tol::Int) -> Vector{arb}

Returns the image of $a$ under the Minkowski embedding. Every entry of the array returned is of type arb with radius less then 2^(-abs_tol).

### Predicates

is_integralMethod
is_integral(a::NumFieldElem) -> Bool

Returns whether $a$ is integral, that is, whether the minimal polynomial of $a$ has integral coefficients.

is_torsion_unitMethod
is_torsion_unit(x::nf_elem, checkisunit::Bool = false) -> Bool

Returns whether $x$ is a torsion unit, that is, whether there exists $n$ such that $x^n = 1$.

If checkisunit is true, it is first checked whether $x$ is a unit of the maximal order of the number field $x$ is lying in.

is_local_normMethod
is_local_norm(L::NumField, a::NumFieldElem, P)

Given a number field $L/K$, an element $a \in K$ and a prime ideal $P$ of $K$, returns whether $a$ is a local norm at $P$.

The number field $L/K$ must be a simple extension of degree 2.

is_norm_divisibleMethod
is_norm_divisible(a::nf_elem, n::fmpz) -> Bool

Checks if the norm of $a$ is divisible by $n$, assuming that the norm of $a$ is an integer.

is_normMethod
is_norm(K::AnticNumberField, a::fmpz; extra::Vector{fmpz}) -> Bool, nf_elem

For a fmpz $a$, try to find $T \in K$ s.th. $N(T) = a$ holds. If successful, return true and $T$, otherwise false and some element. In \testtt{extra} one can pass in additional prime numbers that are allowed to occur in the solution. This will then be supplemented. The element will be returned in factored form.

### Invariants

normMethod
norm(a::NumFieldElem) -> NumFieldElem

Returns the norm of an element $a$ of a number field extension $L/K$. This will be an element of $K$.

absolute_normMethod
absolute_norm(a::NumFieldElem) -> fmpq

Given a number field element $a$, returns the absolute norm of $a$.

minpolyMethod
minpoly(a::NumFieldElem) -> PolyElem

Given a number field element $a$ of a number field $K$, this function returns the minimal polynomial of $a$ over the base field of $K$.

absolute_minpolyMethod
absolute_minpoly(a::NumFieldElem) -> PolyElem

Given a number field element $a$ of a number field $K$, this function returns the minimal polynomial of $a$ over the rationals $\mathbf{Q}$.

charpolyMethod
charpoly(a::NumFieldElem) -> PolyElem

Given a number field element $a$ of a number field $K$, this function returns the characteristic polynomial of $a$ over the base field of $K$.

absolute_charpolyMethod
absolute_charpoly(a::NumFieldElem) -> PolyElem

Given a number field element $a$ of a number field $K$, this function returns the characteristic polynomial of $a$ over the rationals $\mathbf{Q}$.

normMethod
norm(a::NumFieldElem, k::NumField) -> NumFieldElem

Returns the norm of an element $a$ of a number field $L$ with respect to a subfield $k$ of $L$. This will be an element of $k$.