* rnf denotes a relative number field, i.e. a data structure output by rnfinit, attached to the extension L/K. The nf attached to be base field K is rnf.nf.

* A relative matrix is an m x n matrix whose entries are elements of K, in any form. Its m columns A_j represent elements in Kⁿ.

* An ideal list is a row vector of fractional ideals of the number field nf.

* A pseudo-matrix is a 2-component row vector (A,I) where A is a relative m x n matrix and I an ideal list of length n. If I = {𝔞₁,..., 𝔞_n} and the columns of A are (A₁,..., A_n), this data defines the torsion-free (projective) ℤ_K-module 𝔞₁ A₁⨁ 𝔞_n A_n.

* An integral pseudo-matrix is a 3-component row vector (A,I,J) where A = (a_i,j) is an m x n relative matrix and I = (𝔟₁,..., 𝔟_m), J = (𝔞₁,..., 𝔞_n) are ideal lists, such that a_i,j ∈ 𝔟_i 𝔞_j^-1 for all i,j. This data defines two abstract projective ℤ_K-modules N = 𝔞₁ω₁⨁ ...⨁ 𝔞_nω_n in Kⁿ, P = 𝔟₁η₁⨁ ...⨁ 𝔟_mη_m in K^m, and a ℤ_K-linear map f:N → P given by f(∑_j α_jω_j) = ∑_i (a_i,jα_j) η_i. This data defines the ℤ_K-module M = P/f(N).

* Any projective ℤ_K-moduleprojective module M of finite type in K^m can be given by a pseudo matrix (A,I).

* An arbitrary ℤ_K module of finite type in K^m, with nontrivial torsion, is given by an integral pseudo-matrix (A,I,J)

We are given a number field K = nfinit(T), attached to K = ℚ[Y]/(T), T ∈ ℚ[Y], and a relative extension L = rnfinit(K, P), attached to L = K[X]/(P), P ∈ K[X]. In all contexts (except rnfeltabstorel and rnfeltdown, see below), an algebraic number is given as

* a t_INT, t_FRAC or t_POL in ℚ[Y] (implicitly modulo T) or a t_POL in K[X] (implicitly modulo P),

* a t_POLMOD (modulo T or P), or

* a t_COL v of dimension m = [K:ℚ], representing the element in terms of the integral basis K.zk;

* if an absolute nf structure Labs was attached to L, via Labs = nfinit(L), then we can also use a t_COL v of dimension [L:ℚ], representing the element in terms of the computed integral basis Labs.zk. Be careful that in the degenerate case L = K, then the previous interpretation (with respect to K.zk) takes precedence. This is no concern when K = ℚ or if P = X - Y (because in that case the primitive polynomial Labs.pol defining L of ℚ is nf.pol and the computation of nf.zk is deterministic); but in other cases, the integer bases attached to K and Labs may differ.

Special case: rnfeltabstorel and rnfeltdown. These two functions assume that elements are given in absolute representation (with respect to Labs.zk or modulo Labs.pol and converts them to relative representation modulo L.pol. In these two functions (only), a t_POL in X is implicitly understood modulo Labs.pol and a t_COL of length [L:ℚ] refers to the integral basis Labs.zk in all cases, including L = K.

* The pair (A,I) is a pseudo-basis of the module it generates if the 𝔞_j are nonzero, and the A_j are K-linearly independent. We call n the size of the pseudo-basis. If A is a relative matrix, the latter condition means it is square with nonzero determinant; we say that it is in Hermite Normal Form (HNF) if it is upper triangular and all the elements of the diagonal are equal to 1.

* For instance, the relative integer basis rnf.zk is a pseudo-basis (A,I) of ℤ_L, where A = rnf.zk[1] is a vector of elements of L, which are K-linearly independent. Most rnf routines return and handle ℤ_K-modules contained in L (e.g. ℤ_L-ideals) via a pseudo-basis (A',I'), where A' is a relative matrix representing a vector of elements of L in terms of the fixed basis rnf.zk[1]

* The determinant of a pseudo-basis (A,I) is the ideal equal to the product of the determinant of A by all the ideals of I. The determinant of a pseudo-matrix is the determinant of any pseudo-basis of the module it generates.

Given a pseudo-matrix x, computes a nonzero ideal contained in (i.e. multiple of) the determinant of x. This is particularly useful in conjunction with nfhnfmod.

The library syntax is GEN nfdetint(GEN nf, GEN x).

Given a pseudo-matrix (A,I), finds a pseudo-basis (B,J) in Hermite normal form of the module it generates. If flag is nonzero, also return the transformation matrix U such that AU = [0|B].

The library syntax is GEN nfhnf0(GEN nf, GEN x, long flag). Also available:

GEN nfhnf(GEN nf, GEN x) (flag = 0).

GEN rnfsimplifybasis(GEN bnf, GEN x) simplifies the pseudo-basis x = (A,I), returning a pseudo-basis (B,J). The ideals in the list J are integral, primitive and either trivial (equal to the full ring of integer) or nonprincipal.

Given a pseudo-matrix (A,I) and an ideal detx which is contained in (read integral multiple of) the determinant of (A,I), finds a pseudo-basis in Hermite normal form of the module generated by (A,I). This avoids coefficient explosion. detx can be computed using the function nfdetint.

The library syntax is GEN nfhnfmod(GEN nf, GEN x, GEN detx).

Given a torsion ℤ_K-module x attached to the square integral invertible pseudo-matrix (A,I,J), returns an ideal list D = [d₁,...,d_n] which is the Smith normal form of x. In other words, x is isomorphic to ℤ_K/d₁⨁ ...⨁ ℤ_K/d_n and d_i divides d_i-1 for i ≥ 2. If flag is nonzero return [D,U,V], where UAV is the identity.

See Section se:ZKmodules for the definition of integral pseudo-matrix; briefly, it is input as a 3-component row vector [A,I,J] where I = [b₁,...,b_n] and J = [a₁,...,a_n] are two ideal lists, and A is a square n x n matrix with columns (A₁,...,A_n), seen as elements in Kⁿ (with canonical basis (e₁,...,e_n)). This data defines the ℤ_K module x given by (b₁e₁⨁ ...⨁ b_ne_n) / (a₁A₁⨁ ...⨁ a_nA_n) , The integrality condition is a_i,j ∈ b_i a_j^-1 for all i,j. If it is not satisfied, then the d_i will not be integral. Note that every finitely generated torsion module is isomorphic to a module of this form and even with b_i = Z_K for all i.

The library syntax is GEN nfsnf0(GEN nf, GEN x, long flag). Also available:

GEN nfsnf(GEN nf, GEN x) (flag = 0).

Expresses x on the relative integral basis. Here, rnf is a relative number field extension L/K as output by rnfinit, and x an element of L in absolute form, i.e. expressed as a polynomial or polmod with polmod coefficients, not on the relative integral basis.

The library syntax is GEN rnfalgtobasis(GEN rnf, GEN x).

Let K the field represented by bnf, as output by bnfinit. M is a projective ℤ_K-module of rank n (M ⨂ K is an n-dimensional K-vector space), given by a pseudo-basis of size n. The routine returns either a true ℤ_K-basis of M (of size n) if it exists, or an n+1-element generating set of M if not.

It is allowed to use a monic irreducible polynomial P in K[X] instead of M, in which case, M is defined as the ring of integers of K[X]/(P), viewed as a ℤ_K-module.

Huge discriminants, helping rnfdisc. The format [T,B] is also accepted instead of T and computes an order which is maximal at all maximal ideals specified by B, see ??rnfinit: the valuation of D is then correct at all such maximal ideals but may be incorrect at other primes.

The library syntax is GEN rnfbasis(GEN bnf, GEN M).

Computes the representation of x as a polmod with polmods coefficients. Here, rnf is a relative number field extension L/K as output by rnfinit, and x an element of L expressed on the relative integral basis.

The library syntax is GEN rnfbasistoalg(GEN rnf, GEN x).

Characteristic polynomial of a over nf, where a belongs to the algebra defined by T over nf, i.e. nf[X]/(T). Returns a polynomial in variable v (x by default).

  ? nf = nfinit(y^2+1);
  ? rnfcharpoly(nf, x^2+y*x+1, x+y)
  %2 = x^2 + Mod(-y, y^2 + 1)*x + 1

The library syntax is GEN rnfcharpoly(GEN nf, GEN T, GEN a, long var = -1) where var is a variable number.

Given a bnf structure attached to a number field K, as produced by bnfinit, and T an irreducible polynomial in K[x] defining an Abelian extension L = K[x]/(T), computes the class field theory conductor of this Abelian extension. If T does not define an Abelian extension over K, the result is undefined; it may be the integer 0 (in which case the extension is definitely not Abelian) or a wrong result.

The result is a 3-component vector [f,bnr,H], where f is the conductor of the extension given as a 2-component row vector [f₀,f _oo ], bnr is the attached bnr structure and H is a matrix in HNF defining the subgroup of the ray class group on the ray class group generators bnr.gen; in particular, it is a left divisor of the diagonal matrix attached to bnr.cyc and |det H |= N = deg T.

* If flag is 1, return [f,bnrmod, H], where bnrmod is now attached to Cl_f / Cl_f^N, and H is as before since it contains the N-th powers. This is useful when f contains a maximal ideal with huge residue field, since the corresponding tough discrete logarithms are trivialized: in the quotient group, all elements have small order dividing N. This allows to work in Cl_f/H but no longer in Cl_f.

* If flag is 2, only return [f, fa] where fa is the factorization of the conductor finite part ( = f[1]).

Huge discriminants, helping rnfdisc. The format [T,B] is also accepted instead of T and computes the conductor of the extension provided it factors completely over the maximal ideals specified by B, see ??rnfinit: the valuation of f₀ is then correct at all such maximal ideals but may be incorrect at other primes.

The library syntax is GEN rnfconductor0(GEN bnf, GEN T, long flag). Also available is GEN rnfconductor(GEN bnf, GEN T) when flag = 0.

Given a number field K coded by nf and a monic polynomial P ∈ ℤ_K[X], irreducible over K and thus defining a relative extension L of K, applies Dedekind's criterion to the order ℤ_K[X]/(P), at the prime ideal pr. It is possible to set pr to a vector of prime ideals (test maximality at all primes in the vector), or to omit altogether, in which case maximality at all primes is tested; in this situation flag is automatically set to 1.

The default historic behavior (flag is 0 or omitted and pr is a single prime ideal) is not so useful since rnfpseudobasis gives more information and is generally not that much slower. It returns a 3-component vector [max, basis, v]:

* basis is a pseudo-basis of an enlarged order O produced by Dedekind's criterion, containing the original order ℤ_K[X]/(P) with index a power of pr. Possibly equal to the original order.

* max is a flag equal to 1 if the enlarged order O could be proven to be pr-maximal and to 0 otherwise; it may still be maximal in the latter case if pr is ramified in L,

* v is the valuation at pr of the order discriminant.

If flag is nonzero, on the other hand, we just return 1 if the order ℤ_K[X]/(P) is pr-maximal (resp. maximal at all relevant primes, as described above), and 0 if not. This is much faster than the default, since the enlarged order is not computed.

  ? nf = nfinit(y^2-3); P = x^3 - 2*y;
  ? pr3 = idealprimedec(nf,3)[1];
  ? rnfdedekind(nf, P, pr3)
  %3 = [1, [[1, 0, 0; 0, 1, 0; 0, 0, 1], [1, 1, 1]], 8]
  ? rnfdedekind(nf, P, pr3, 1)
  %4 = 1

In this example, pr3 is the ramified ideal above 3, and the order generated by the cube roots of y is already pr3-maximal. The order-discriminant has valuation 8. On the other hand, the order is not maximal at the prime above 2:

  ? pr2 = idealprimedec(nf,2)[1];
  ? rnfdedekind(nf, P, pr2, 1)
  %6 = 0
  ? rnfdedekind(nf, P, pr2)
  %7 = [0, [[2, 0, 0; 0, 1, 0; 0, 0, 1], [[1, 0; 0, 1], [1, 0; 0, 1],
       [1, 1/2; 0, 1/2]]], 2]

The enlarged order is not proven to be pr2-maximal yet. In fact, it is; it is in fact the maximal order:

  ? B = rnfpseudobasis(nf, P)
  %8 = [[1, 0, 0; 0, 1, 0; 0, 0, 1], [1, 1, [1, 1/2; 0, 1/2]],
       [162, 0; 0, 162], -1]
  ? idealval(nf,B[3], pr2)
  %9 = 2

It is possible to use this routine with nonmonic P = ∑_{i ≤ n} p_i Xⁱ ∈ ℤ_K[X] if flag = 1; in this case, we test maximality of Dedekind's order generated by 1, p_n α, p_nα² + p_n-1α,..., p_nα^n-1 + p_n-1α^n-2 +...+ p₁α. The routine will fail if P vanishes on the projective line over the residue field ℤ_K/pr (FIXME).

The library syntax is GEN rnfdedekind(GEN nf, GEN pol, GEN pr = NULL, long flag).

Given a pseudo-matrix M over the maximal order of nf, computes its determinant.

The library syntax is GEN rnfdet(GEN nf, GEN M).

Given an nf structure attached to a number field K, as output by nfinit, and a monic irreducible polynomial T ∈ K[x] defining a relative extension L = K[x]/(T), compute the relative discriminant of L. This is a vector [D,d], where D is the relative ideal discriminant and d is the relative discriminant considered as an element of K^*/{K^*}². The main variable of nf must be of lower priority than that of T, see Section se:priority.

Huge discriminants, helping rnfdisc. The format [T,B] is also accepted instead of T and computes an order which is maximal at all maximal ideals specified by B, see ??rnfinit: the valuation of D is then correct at all such maximal ideals but may be incorrect at other primes.

The library syntax is GEN rnfdiscf(GEN nf, GEN T).

Let rnf be a relative number field extension L/K as output by rnfinit and let x be an element of L expressed either

* as a polynomial modulo the absolute equation rnf.polabs,

* or in terms of the absolute ℤ-basis for ℤ_L if rnf contains one (as in rnfinit(nf,pol,1), or after a call to nfinit(rnf)).

Computes x as an element of the relative extension L/K as a polmod with polmod coefficients. If x is actually rational, return it as a rational number:

  ? K = nfinit(y^2+1); L = rnfinit(K, x^2-y);
  ? L.polabs
  %2 = x^4 + 1
  ? rnfeltabstorel(L, Mod(x, L.polabs))
  %3 = Mod(x, x^2 + Mod(-y, y^2 + 1))
  ? rnfeltabstorel(L, 1/3)
  %4 = 1/3
  ? rnfeltabstorel(L, Mod(x, x^2-y))
  %5 = Mod(x, x^2 + Mod(-y, y^2 + 1))
  
  ? rnfeltabstorel(L, [0,0,0,1]~) \\ ZL not initialized yet
   ***   at top-level: rnfeltabstorel(L,[0,
   ***                 ^ —  —  —  —  —  — --
   *** rnfeltabstorel: incorrect type in rnfeltabstorel, apply nfinit(rnf).
  ? nfinit(L); \\ initialize now
  ? rnfeltabstorel(L, [0,0,0,1]~)
  %6 = Mod(Mod(y, y^2 + 1)*x, x^2 + Mod(-y, y^2 + 1))
  ? rnfeltabstorel(L, [1,0,0,0]~)
  %7 = 1

The library syntax is GEN rnfeltabstorel(GEN rnf, GEN x).

rnf being a relative number field extension L/K as output by rnfinit and x being an element of L expressed as a polynomial or polmod with polmod coefficients (or as a t_COL on nfinit(rnf).zk), computes x as an element of K as a t_POLMOD if flag = 0 and as a t_COL otherwise. If x is not in K, a domain error occurs. Note that if x is in fact rational, it is returned as a rational number, ignoring flag.

  ? K = nfinit(y^2+1); L = rnfinit(K, x^2-y);
  ? L.pol
  %2 = x^4 + 1
  ? rnfeltdown(L, Mod(x^2, L.pol))
  %3 = Mod(y, y^2 + 1)
  ? rnfeltdown(L, Mod(x^2, L.pol), 1)
  %4 = [0, 1]~
  ? rnfeltdown(L, Mod(y, x^2-y))
  %5 = Mod(y, y^2 + 1)
  ? rnfeltdown(L, Mod(y,K.pol))
  %6 = Mod(y, y^2 + 1)
  ? rnfeltdown(L, Mod(x, L.pol))
   ***   at top-level: rnfeltdown(L,Mod(x,x
   ***                 ^ —  —  —  —  —  — --
   *** rnfeltdown: domain error in rnfeltdown: element not in the base field
  ? rnfeltdown(L, Mod(y, x^2-y), 1) \\ as a t_COL
  %7 = [0, 1]~
  ? rnfeltdown(L, [0,0,1,0]~) \\ not allowed without absolute nf struct
    *** rnfeltdown: incorrect type in rnfeltdown (t_COL).
  ? nfinit(L); \\ add absolute nf structure to L
  ? rnfeltdown(L, [0,0,1,0]~) \\ now OK
  %8 = Mod(y, y^2 + 1)

If we had started with L = rnfinit(K, x^2-y, 1), then the final command would have worked directly.

The library syntax is GEN rnfeltdown0(GEN rnf, GEN x, long flag). Also available is GEN rnfeltdown(GEN rnf, GEN x) (flag = 0).

rnf being a relative number field extension L/K as output by rnfinit and x being an element of L, returns the relative norm N_L/K(x) as an element of K.

  ? K = nfinit(y^2+1); L = rnfinit(K, x^2-y);
  ? rnfeltnorm(L, Mod(x, L.pol))
  %2 = Mod(x, x^2 + Mod(-y, y^2 + 1))
  ? rnfeltnorm(L, 2)
  %3 = 4

The library syntax is GEN rnfeltnorm(GEN rnf, GEN x).

rnf being a relative number field extension L/K as output by rnfinit and x being an element of L expressed as a polynomial or polmod with polmod coefficients, computes x as an element of the absolute extension L/ℚ as a polynomial modulo the absolute equation rnf.polabs.

  ? K = nfinit(y^2+1); L = rnfinit(K, x^2-y);
  ? L.polabs
  %2 = x^4 + 1
  ? rnfeltreltoabs(L, Mod(x, L.pol))
  %3 = Mod(x, x^4 + 1)
  ? rnfeltreltoabs(L, Mod(y, x^2-y))
  %4 = Mod(x^2, x^4 + 1)
  ? rnfeltreltoabs(L, Mod(y,K.pol))
  %5 = Mod(x^2, x^4 + 1)

If the input is actually rational, then rnfeltreltoabs returns it as a rational number instead of a t_POLMOD:

  ? rnfeltreltoabs(L, Mod(2, K.pol))
  %6 = 2

The library syntax is GEN rnfeltreltoabs(GEN rnf, GEN x).

rnf being a relative number field extension L/K as output by rnfinit and x being an element of L, returns the relative trace Tr_L/K(x) as an element of K.

  ? K = nfinit(y^2+1); L = rnfinit(K, x^2-y);
  ? rnfelttrace(L, Mod(x, L.pol))
  %2 = 0
  ? rnfelttrace(L, 2)
  %3 = 4

The library syntax is GEN rnfelttrace(GEN rnf, GEN x).

rnf being a relative number field extension L/K as output by rnfinit and x being an element of K, computes x as an element of the absolute extension L/ℚ. As a t_POLMOD modulo rnf.pol if flag = 0 and as a t_COL on the absolute field integer basis if flag = 1. Note that if x is in fact rational, it is returned as a rational number, ignoring flag.

  ? K = nfinit(y^2+1); L = rnfinit(K, x^2-y);
  ? L.pol
  %2 = x^4 + 1
  ? rnfeltup(L, Mod(y, K.pol))
  %3 = Mod(x^2, x^4 + 1)
  ? rnfeltup(L, y)
  %4 = Mod(x^2, x^4 + 1)
  ? rnfeltup(L, [1,2]~) \\ in terms of K.zk
  %5 = Mod(2*x^2 + 1, x^4 + 1)
  ? rnfeltup(L, y, 1) \\ in terms of nfinit(L).zk
  %6 = [0, 1, 0, 0]~
  ? rnfeltup(L, [1,2]~, 1)
  %7 = [1, 2, 0, 0]~
  ? rnfeltup(L, [1,0]~) \\ rational
  %8 = 1

The library syntax is GEN rnfeltup0(GEN rnf, GEN x, long flag). Also available is GEN rnfeltup(GEN rnf, GEN x) (flag = 0).

Given a number field nf as output by nfinit (or simply a monic irreducible integral polynomial defining the field) and a polynomial pol with coefficients in nf defining a relative extension L of nf, computes an absolute equation of L over ℚ.

The main variable of nf must be of lower priority than that of pol (see Section se:priority). Note that for efficiency, this does not check whether the relative equation is irreducible over nf, but only if it is squarefree. If it is reducible but squarefree, the result will be the absolute equation of the étale algebra defined by pol. If pol is not squarefree, raise an e_DOMAIN exception.

  ? rnfequation(y^2+1, x^2 - y)
  %1 = x^4 + 1
  ? T = y^3-2; rnfequation(nfinit(T), (x^3-2)/(x-Mod(y,T)))
  %2 = x^6 + 108  \\ Galois closure of Q(2^(1/3))

If flag is nonzero, outputs a 3-component row vector [z,a,k], where

* z is the absolute equation of L over ℚ, as in the default behavior,

* a expresses as a t_POLMOD modulo z a root α of the polynomial defining the base field nf,

* k is a small integer such that θ = β+kα is a root of z, where β is a root of pol. It is guaranteed that k = 0 whenever ℚ(β) = L.

  ? T = y^3-2; pol = x^2 +x*y + y^2;
  ? [z,a,k] = rnfequation(T, pol, 1);
  ? z
  %3 = x^6 + 108
  ? subst(T, y, a)
  %4 = 0
  ? alpha= Mod(y, T);
  ? beta = Mod(x*Mod(1,T), pol);
  ? subst(z, x, beta + k*alpha)
  %7 = 0

The library syntax is GEN rnfequation0(GEN nf, GEN pol, long flag). Also available are GEN rnfequation(GEN nf, GEN pol) (flag = 0) and GEN rnfequation2(GEN nf, GEN pol) (flag = 1).

Given a bnf attached to a number field K and a projective ℤ_K-module M given by a pseudo-matrix, returns either a true HNF basis of M if one exists, or zero otherwise. If M is a polynomial with coefficients in K, replace it by the pseudo-matrix returned by rnfpseudobasis.

The library syntax is GEN rnfhnfbasis(GEN bnf, GEN M).

Let rnf be a relative number field extension L/K as output by rnfinit and let x be an ideal of the absolute extension L/ℚ. Returns the relative pseudo-matrix in HNF giving the ideal x considered as an ideal of the relative extension L/K, i.e. as a ℤ_K-module.

Let Labs be an (absolute) nf structure attached to L, obtained via Labs = nfinit(rnf)). Then rnf "knows" about Labs and x may be given in any format attached to Labs, e.g. a prime ideal or an ideal in HNF wrt. Labs.zk:

  ? K = nfinit(y^2+1); rnf = rnfinit(K, x^2-y); Labs = nfinit(rnf);
  ? m = idealhnf(Labs, 17, x^3+2); \\ some ideal in HNF wrt. Labs.zk
  ? B = rnfidealabstorel(rnf, m)
  %3 = [[1, 8; 0, 1], [[17, 4; 0, 1], 1]] \\ pseudo-basis for m as ZK-module
  ? A = rnfidealreltoabs(rnf, B)
  %4 = [17, x^2 + 4, x + 8, x^3 + 8*x^2]  \\ Z-basis for m in Q[x]/(rnf.polabs)
  ? mathnf(matalgtobasis(Labs, A)) == m
  %5 = 1

If on the other hand, we do not have a Labs at hand, because it would be too expensive to compute, but we nevertheless have a ℤ-basis for x, then we can use the function with this basis as argument. The entries of x may be given either modulo rnf.polabs (absolute form, possibly lifted) or modulo rnf.pol (relative form as t_POLMODs):

  ? K = nfinit(y^2+1); rnf = rnfinit(K, x^2-y);
  ? rnfidealabstorel(rnf, [17, x^2 + 4, x + 8, x^3 + 8*x^2])
  %2 = [[1, 8; 0, 1], [[17, 4; 0, 1], 1]]
  ? rnfidealabstorel(rnf, Mod([17, y + 4, x + 8, y*x + 8*y], x^2-y))
  %3 = [[1, 8; 0, 1], [[17, 4; 0, 1], 1]]

The library syntax is GEN rnfidealabstorel(GEN rnf, GEN x).

Let rnf be a relative number field extension L/K as output by rnfinit, and x an ideal of L, given either in relative form or by a ℤ-basis of elements of L (see Section se:rnfidealabstorel). This function returns the ideal of K below x, i.e. the intersection of x with K.

The library syntax is GEN rnfidealdown(GEN rnf, GEN x).

Factor into prime ideal powers the ideal x in the attached absolute number field L = nfinit(rnf). The output format is similar to the factor function, and the prime ideals are represented in the form output by the idealprimedec function for L.

  ? rnf = rnfinit(nfinit(y^2+1), x^2-y+1);
  ? rnfidealfactor(rnf, y+1)  \\ P2^2
  %2 =
  [[2, [0,0,1,0]~, 4, 1, [0,0,0,2;0,0,-2,0;-1,-1,0,0;1,-1,0,0]] 2]
  
  ? rnfidealfactor(rnf, x) \\ P2
  %3 =
  [[2, [0,0,1,0]~, 4, 1, [0,0,0,2;0,0,-2,0;-1,-1,0,0;1,-1,0,0]] 1]
  
  ? L = nfinit(rnf);
  ? id = idealhnf(L, idealhnf(L, 25, (x+1)^2));
  ? idealfactor(L, id) == rnfidealfactor(rnf, id)
  %6 = 1

Note that ideals of the base field K must be explicitly lifted to L via rnfidealup before they can be factored.

The library syntax is GEN rnfidealfactor(GEN rnf, GEN x).

rnf being a relative number field extension L/K as output by rnfinit and x being a relative ideal (which can be, as in the absolute case, of many different types, including of course elements), computes the HNF pseudo-matrix attached to x, viewed as a ℤ_K-module.

The library syntax is GEN rnfidealhnf(GEN rnf, GEN x).

rnf being a relative number field extension L/K as output by rnfinit and x and y being ideals of the relative extension L/K given by pseudo-matrices, outputs the ideal product, again as a relative ideal.

The library syntax is GEN rnfidealmul(GEN rnf, GEN x, GEN y).

Let rnf be a relative number field extension L/K as output by rnfinit and let x be a relative ideal (which can be, as in the absolute case, of many different types, including of course elements). This function computes the norm of the x considered as an ideal of the absolute extension L/ℚ. This is identical to

     idealnorm(rnf, rnfidealnormrel(rnf,x))

but faster.

The library syntax is GEN rnfidealnormabs(GEN rnf, GEN x).

Let rnf be a relative number field extension L/K as output by rnfinit and let x be a relative ideal (which can be, as in the absolute case, of many different types, including of course elements). This function computes the relative norm of x as an ideal of K in HNF.

The library syntax is GEN rnfidealnormrel(GEN rnf, GEN x).

Let rnf be a relative number field extension L/K as output by rnfinit, and pr a maximal ideal of K (prid), this function completes the rnf with a nf structure attached to L (see Section se:rnfinit) and returns the vector S of prime ideals of ℤ_L above pr.

  ? K = nfinit(y^2+1); rnf = rnfinit(K, x^3+y+1);
  ? pr = idealprimedec(K, 2)[1];
  ? S = rnfidealprimedec(rnf, pr);
  ? #S
  %4 = 1

The relative ramification indices and residue degrees can be obtained as PR.e / pr.e and PR.f / PR.f, if PR is an element of S.

The argument pr is also allowed to be a prime number p, in which case the function returns a pair of vectors [SK,SL], where SK contains the primes of K above p and SL[i] is the vector of primes of L above SK[i].

  ? [SK,SL] = rnfidealprimedec(rnf, 5);
  ? [#SK, vector(#SL,i,#SL[i])]
  %6 = [2, [2, 2]]

The library syntax is GEN rnfidealprimedec(GEN rnf, GEN pr).

Let rnf be a relative number field extension L/K as output by rnfinit and let x be a relative ideal, given as a ℤ_K-module by a pseudo matrix [A,I]. This function returns the ideal x as an absolute ideal of L/ℚ. If flag = 0, the result is given by a vector of t_POLMODs modulo rnf.pol forming a ℤ-basis; if flag = 1, it is given in HNF in terms of the fixed ℤ-basis for ℤ_L, see Section se:rnfinit.

  ? K = nfinit(y^2+1); rnf = rnfinit(K, x^2-y);
  ? P = idealprimedec(K,2)[1];
  ? P = rnfidealup(rnf, P)
  %3 = [2, x^2 + 1, 2*x, x^3 + x]
  ? Prel = rnfidealhnf(rnf, P)
  %4 = [[1, 0; 0, 1], [[2, 1; 0, 1], [2, 1; 0, 1]]]
  ? rnfidealreltoabs(rnf,Prel)
  %5 = [2, x^2 + 1, 2*x, x^3 + x]
  ? rnfidealreltoabs(rnf,Prel,1)
  %6 =
  [2 1 0 0]
  
  [0 1 0 0]
  
  [0 0 2 1]
  
  [0 0 0 1]

The reason why we do not return by default (flag = 0) the customary HNF in terms of a fixed ℤ-basis for ℤ_L is precisely because a rnf does not contain such a basis by default. Completing the structure so that it contains a nf structure for L is polynomial time but costly when the absolute degree is large, thus it is not done by default. Note that setting flag = 1 will complete the rnf.

The library syntax is GEN rnfidealreltoabs0(GEN rnf, GEN x, long flag). Also available is GEN rnfidealreltoabs(GEN rnf, GEN x) (flag = 0).

rnf being a relative number field extension L/K as output by rnfinit and x being an ideal of the relative extension L/K given by a pseudo-matrix, gives a vector of two generators of x over ℤ_L expressed as polmods with polmod coefficients.

The library syntax is GEN rnfidealtwoelement(GEN rnf, GEN x).

Let rnf be a relative number field extension L/K as output by rnfinit and let x be an ideal of K. This function returns the ideal xℤ_L as an absolute ideal of L/ℚ, in the form of a ℤ-basis. If flag = 0, the result is given by a vector of polynomials (modulo rnf.pol); if flag = 1, it is given in HNF in terms of the fixed ℤ-basis for ℤ_L, see Section se:rnfinit.

  ? K = nfinit(y^2+1); rnf = rnfinit(K, x^2-y);
  ? P = idealprimedec(K,2)[1];
  ? rnfidealup(rnf, P)
  %3 = [2, x^2 + 1, 2*x, x^3 + x]
  ? rnfidealup(rnf, P,1)
  %4 =
  [2 1 0 0]
  
  [0 1 0 0]
  
  [0 0 2 1]
  
  [0 0 0 1]

The reason why we do not return by default (flag = 0) the customary HNF in terms of a fixed ℤ-basis for ℤ_L is precisely because a rnf does not contain such a basis by default. Completing the structure so that it contains a nf structure for L is polynomial time but costly when the absolute degree is large, thus it is not done by default. Note that setting flag = 1 will complete the rnf.

The library syntax is GEN rnfidealup0(GEN rnf, GEN x, long flag). Also available is GEN rnfidealup(GEN rnf, GEN x) (flag = 0).

Given an nf structure attached to a number field K, as output by nfinit, and a monic irreducible polynomial T in ℤ_K[x] defining a relative extension L = K[x]/(T), this computes data to work in L/K The main variable of T must be of higher priority (see Section se:priority) than that of nf, and the coefficients of T must be in K.

The result is a row vector, whose components are technical. We let m = [K:ℚ] the degree of the base field, n = [L:K] the relative degree, r₁ and r₂ the number of real and complex places of K. Access to this information via member functions is preferred since the specific data organization specified below will change in the future.

If flag = 1, add an nf structure attached to L to rnf. This is likely to be very expensive if the absolute degree mn is large, but fixes an integer basis for ℤ_L as a ℤ-module and allows to input and output elements of L in absolute form: as t_COL for elements, as t_MAT in HNF for ideals, as prid for prime ideals. Without such a call, elements of L are represented as t_POLMOD, etc. Note that a subsequent nfinit(rnf) will also explicitly add such a component, and so will the following functions rnfidealmul, rnfidealtwoelt, rnfidealprimedec, rnfidealup (with flag 1) and rnfidealreltoabs (with flag 1). The absolute nf structure attached to L can be recovered using nfinit(rnf).

rnf[1](rnf.pol) contains the relative polynomial T.

rnf[2] contains the integer basis [A,d] of K, as (integral) elements of L/ℚ. More precisely, A is a vector of polynomial with integer coefficients, d is a denominator, and the integer basis is given by A/d.

rnf[3] (rnf.disc) is a two-component row vector [𝔡(L/K),s] where 𝔡(L/K) is the relative ideal discriminant of L/K and s is the discriminant of L/K viewed as an element of K^*/(K^*)², in other words it is the output of rnfdisc.

rnf[4](rnf.index) is the ideal index 𝔣, i.e. such that d(T)ℤ_K = 𝔣²𝔡(L/K).

rnf[5](rnf.p) is the list of rational primes dividing the norm of the relative discriminant ideal.

rnf[7] (rnf.zk) is the pseudo-basis (A,I) for the maximal order ℤ_L as a ℤ_K-module: A is the relative integral pseudo basis expressed as polynomials (in the variable of T) with polmod coefficients in nf, and the second component I is the ideal list of the pseudobasis in HNF.

rnf[8] is the inverse matrix of the integral basis matrix, with coefficients polmods in nf.

rnf[9] is currently unused.

rnf[10] (rnf.nf) is nf.

rnf[11] is an extension of rnfequation(K, T, 1). Namely, a vector [P, a, k, K.pol, T] describing the absolute extension L/ℚ: P is an absolute equation, more conveniently obtained as rnf.polabs; a expresses the generator α = y mod K.pol of the number field K as an element of L, i.e. a polynomial modulo the absolute equation P;

k is a small integer such that, if β is an abstract root of T and α the generator of K given above, then P(β + kα) = 0. It is guaranteed that k = 0 if ℚ(β) = L.

Caveat. Be careful if k != 0 when dealing simultaneously with absolute and relative quantities since L = ℚ(β + kα) = K(α), and the generator chosen for the absolute extension is not the same as for the relative one. If this happens, one can of course go on working, but we advise to change the relative polynomial so that its root becomes β + k α. Typical GP instructions would be

    [P,a,k] = rnfequation(K, T, 1);
    if (k, T = subst(T, x, x - k*Mod(y, K.pol)));
    L = rnfinit(K, T);

rnf[12] is by default unused and set equal to 0. This field is used to store further information about the field as it becomes available (which is rarely needed, hence would be too expensive to compute during the initial rnfinit call).

Huge discriminants, helping rnfdisc. When T has a discriminant which is difficult to factor, it is hard to compute ℤ_L. As in nfinit, the special input format [T,B] is also accepted, where T is a polynomial as above and B specifies a list of maximal ideals. The following formats are recognized for B:

* an integer: the list of all maximal ideals above a rational prime p < B.

* a vector of rational primes or prime ideals: the list of all maximal ideals dividing an element in the list.

Instead of ℤ_L, this produces an order which is maximal at all such maximal ideals primes. The result may actually be a complete and correct rnf structure if the relative ideal discriminant factors completely over this list of maximal ideals but this is not guaranteed. In general, the order may not be maximal at primes 𝔭 not in the list such that 𝔭² divides the relative ideal discriminant.

The library syntax is GEN rnfinit0(GEN nf, GEN T, long flag). Also available is GEN rnfinit(GEN nf,GEN T) (flag = 0).

T being a relative polynomial with coefficients in nf, return 1 if it defines an abelian extension, and 0 otherwise.

  ? K = nfinit(y^2 + 23);
  ? rnfisabelian(K, x^3 - 3*x - y)
  %2 = 1

The library syntax is long rnfisabelian(GEN nf, GEN T).

Given a bnf attached to a number field K and a projective ℤ_K-module M given by a pseudo-matrix, return true (1) if M is free else return false (0). If M is a polynomial with coefficients in K, replace it by the pseudo-matrix returned by rnfpseudobasis.

The library syntax is long rnfisfree(GEN bnf, GEN M).

Let rnf be a relative number field extension L/K as output by rnfinit whose degree [L:K] is a power of a prime ℓ. Return 1 if the ℓ-extension is locally cyclotomic (locally contained in the cyclotomic ℤ_ℓ-extension of K_v at all places v | ℓ), and 0 if not.

  ? K = nfinit(y^2 + y + 1);
  ? L = rnfinit(K, x^3 - y); /* = K(zeta9), globally cyclotomic */
  ? rnfislocalcyclo(L)
  %3 = 1
  \\ we expect 3-adic continuity by Krasner's lemma
  ? vector(5, i, rnfislocalcyclo(rnfinit(K, x^3 - y + 3^i)))
  %5 = [0, 1, 1, 1, 1]

The library syntax is long rnfislocalcyclo(GEN rnf).

Similar to bnfisnorm but in the relative case. T is as output by rnfisnorminit applied to the extension L/K. This tries to decide whether the element a in K is the norm of some x in the extension L/K.

The output is a vector [x,q], where a = Norm(x)*q. The algorithm looks for a solution x which is an S-integer, with S a list of places of K containing at least the ramified primes, the generators of the class group of L, as well as those primes dividing a. If L/K is Galois, then this is enough but you may want to add more primes to S to produce different elements, possibly smaller; otherwise, flag is used to add more primes to S: all the places above the primes p ≤ flag (resp. p|flag) if flag > 0 (resp. flag < 0).

The answer is guaranteed (i.e. a is a norm iff q = 1) if the field is Galois, or, under GRH, if S contains all primes less than 4log²|disc(M)|, where M is the normal closure of L/K.

If rnfisnorminit has determined (or was told) that L/K is Galois, and flag != 0, a Warning is issued (so that you can set flag = 1 to check whether L/K is known to be Galois, according to T). Example:

  bnf = bnfinit(y^3 + y^2 - 2*y - 1);
  p = x^2 + Mod(y^2 + 2*y + 1, bnf.pol);
  T = rnfisnorminit(bnf, p);
  rnfisnorm(T, 17)

checks whether 17 is a norm in the Galois extension ℚ(β) / ℚ(α), where α³ + α² - 2α - 1 = 0 and β² + α² + 2α + 1 = 0 (it is).

The library syntax is GEN rnfisnorm(GEN T, GEN a, long flag).

Let K be defined by a root of pol, and L/K the extension defined by the polynomial polrel. As usual, pol can in fact be an nf, or bnf, etc; if pol has degree 1 (the base field is ℚ), polrel is also allowed to be an nf, etc. Computes technical data needed by rnfisnorm to solve norm equations Nx = a, for x in L, and a in K.

If flag = 0, does not care whether L/K is Galois or not.

If flag = 1, L/K is assumed to be Galois (unchecked), which speeds up rnfisnorm.

If flag = 2, lets the routine determine whether L/K is Galois.

The library syntax is GEN rnfisnorminit(GEN pol, GEN polrel, long flag).

This function is deprecated, use bnrclassfield.

The library syntax is GEN rnfkummer(GEN bnr, GEN subgp = NULL, long prec).

Given a polynomial pol with coefficients in nf defining a relative extension L and a suborder order of L (of maximal rank), as output by rnfpseudobasis(nf,pol) or similar, gives [[neworder],U], where neworder is a reduced order and U is the unimodular transformation matrix.

The library syntax is GEN rnflllgram(GEN nf, GEN pol, GEN order, long prec).

bnr being a big ray class field as output by bnrinit and pol a relative polynomial defining an Abelian extension, computes the norm group (alias Artin or Takagi group) corresponding to the Abelian extension of bnf = bnr.bnf defined by pol, where the module corresponding to bnr is assumed to be a multiple of the conductor (i.e. pol defines a subextension of bnr). The result is the HNF defining the norm group on the given generators of bnr.gen. Note that neither the fact that pol defines an Abelian extension nor the fact that the module is a multiple of the conductor is checked. The result is undefined if the assumption is not correct, but the function will return the empty matrix [;] if it detects a problem; it may also not detect the problem and return a wrong result.

The library syntax is GEN rnfnormgroup(GEN bnr, GEN pol).

This function is obsolete: use rnfpolredbest instead. Relative version of polred. Given a monic polynomial pol with coefficients in nf, finds a list of relative polynomials defining some subfields, hopefully simpler and containing the original field. In the present version 2.19.0, this is slower and less efficient than rnfpolredbest.

Remark. This function is based on an incomplete reduction theory of lattices over number fields, implemented by rnflllgram, which deserves to be improved.

The library syntax is GEN rnfpolred(GEN nf, GEN pol, long prec).