# Embeddings into ambient fields¶

This module provides classes to handle embeddings of number fields into ambient fields (generally $$\RR$$ or $$\CC$$).

class sage.rings.number_field.number_field_morphisms.CyclotomicFieldEmbedding

Specialized class for converting cyclotomic field elements into a cyclotomic field of higher order. All the real work is done by _lift_cyclotomic_element.

class sage.rings.number_field.number_field_morphisms.EmbeddedNumberFieldConversion

This allows one to cast one number field in another consistently, assuming they both have specified embeddings into an ambient field (by default it looks for an embedding into $$\CC$$).

This is done by factoring the minimal polynomial of the input in the number field of the codomain. This may fail if the element is not actually in the given field.

ambient_field
class sage.rings.number_field.number_field_morphisms.EmbeddedNumberFieldMorphism

This allows one to go from one number field in another consistently, assuming they both have specified embeddings into an ambient field.

If no ambient field is supplied, then the following ambient fields are tried:

• the pushout of the fields where the number fields are embedded;
• the algebraic closure of the previous pushout;
• $$\CC$$.

EXAMPLES:

sage: K.<i> = NumberField(x^2+1,embedding=QQbar(I))
sage: L.<i> = NumberField(x^2+1,embedding=-QQbar(I))
sage: from sage.rings.number_field.number_field_morphisms import EmbeddedNumberFieldMorphism
sage: EmbeddedNumberFieldMorphism(K,L,CDF)
Generic morphism:
From: Number Field in i with defining polynomial x^2 + 1
To:   Number Field in i with defining polynomial x^2 + 1
Defn: i -> -i
sage: EmbeddedNumberFieldMorphism(K,L,QQbar)
Generic morphism:
From: Number Field in i with defining polynomial x^2 + 1
To:   Number Field in i with defining polynomial x^2 + 1
Defn: i -> -i

ambient_field
section()

EXAMPLES:

sage: from sage.rings.number_field.number_field_morphisms import EmbeddedNumberFieldMorphism
sage: K.<a> = NumberField(x^2-700, embedding=25)
sage: L.<b> = NumberField(x^6-700, embedding=3)
sage: f = EmbeddedNumberFieldMorphism(K, L)
sage: f(2*a-1)
2*b^3 - 1
sage: g = f.section()
sage: g(2*b^3-1)
2*a - 1

class sage.rings.number_field.number_field_morphisms.NumberFieldEmbedding

If R is a lazy field, the closest root to gen_embedding will be chosen.

EXAMPLES:

sage: x = polygen(QQ)
sage: from sage.rings.number_field.number_field_morphisms import NumberFieldEmbedding
sage: K.<a> = NumberField(x^3-2)
sage: f = NumberFieldEmbedding(K, RLF, 1)
sage: f(a)^3
2.00000000000000?
sage: RealField(200)(f(a)^3)
2.0000000000000000000000000000000000000000000000000000000000

sage: sigma_a = K.polynomial().change_ring(CC).roots()[1][0]; sigma_a
-0.62996052494743... - 1.09112363597172*I
sage: g = NumberFieldEmbedding(K, CC, sigma_a)
sage: g(a+1)
0.37003947505256... - 1.09112363597172*I

gen_image()

Returns the image of the generator under this embedding.

EXAMPLES:

sage: f = QuadraticField(7, 'a', embedding=2).coerce_embedding()
sage: f.gen_image()
2.645751311064591?

sage.rings.number_field.number_field_morphisms.closest(target, values, margin=1)

This is a utility function that returns the item in values closest to target (with respect to the code{abs} function). If margin is greater than 1, and x and y are the first and second closest elements to target, then only return x if x is margin times closer to target than y, i.e. margin * abs(target-x) < abs(target-y).

sage.rings.number_field.number_field_morphisms.create_embedding_from_approx(K, gen_image)

Return an embedding of K determined by gen_image.

The codomain of the embedding is the parent of gen_image or, if gen_image is not already an exact root of the defining polynomial of K, the corresponding lazy field. The embedding maps the generator of K to a root of the defining polynomial of K closest to gen_image.

EXAMPLES:

sage: from sage.rings.number_field.number_field_morphisms import create_embedding_from_approx
sage: K.<a> = NumberField(x^3-x+1/10)
sage: create_embedding_from_approx(K, 1)
Generic morphism:
From: Number Field in a with defining polynomial x^3 - x + 1/10
To:   Real Lazy Field
Defn: a -> 0.9456492739235915?
sage: create_embedding_from_approx(K, 0)
Generic morphism:
From: Number Field in a with defining polynomial x^3 - x + 1/10
To:   Real Lazy Field
Defn: a -> 0.10103125788101081?
sage: create_embedding_from_approx(K, -1)
Generic morphism:
From: Number Field in a with defining polynomial x^3 - x + 1/10
To:   Real Lazy Field
Defn: a -> -1.046680531804603?


We can define embeddings from one number field to another:

sage: L.<b> = NumberField(x^6-x^2+1/10)
sage: create_embedding_from_approx(K, b^2)
Generic morphism:
From: Number Field in a with defining polynomial x^3 - x + 1/10
To:   Number Field in b with defining polynomial x^6 - x^2 + 1/10
Defn: a -> b^2


If the embedding is exact, it must be valid:

sage: create_embedding_from_approx(K, b)
Traceback (most recent call last):
...
ValueError: b is not a root of x^3 - x + 1/10

sage.rings.number_field.number_field_morphisms.matching_root(poly, target, ambient_field=None, margin=1, max_prec=None)

Given a polynomial and a target, this function chooses the root that target best approximates as compared in ambient_field.

If the parent of target is exact, the equality is required, otherwise find closest root (with respect to the code{abs} function) in the ambient field to the target, and return the root of poly (if any) that approximates it best.

EXAMPLES:

sage: from sage.rings.number_field.number_field_morphisms import matching_root
sage: R.<x> = CC[]
sage: matching_root(x^2-2, 1.5)
1.41421356237310
sage: matching_root(x^2-2, -100.0)
-1.41421356237310
sage: matching_root(x^2-2, .00000001)
1.41421356237310
sage: matching_root(x^3-1, CDF.0)
-0.50000000000000... + 0.86602540378443...*I
sage: matching_root(x^3-x, 2, ambient_field=RR)
1.00000000000000

sage.rings.number_field.number_field_morphisms.root_from_approx(f, a)

Return an exact root of the polynomial $$f$$ closest to $$a$$.

INPUT:

• f – polynomial with rational coefficients
• a – element of a ring

OUTPUT:

A root of f in the parent of a or, if a is not already an exact root of f, in the corresponding lazy field. The root is taken to be closest to a among all roots of f.

EXAMPLES:

sage: from sage.rings.number_field.number_field_morphisms import root_from_approx
sage: R.<x> = QQ[]

sage: root_from_approx(x^2 - 1, -1)
-1
sage: root_from_approx(x^2 - 2, 1)
1.414213562373095?
sage: root_from_approx(x^3 - x - 1, RR(1))
1.324717957244746?
sage: root_from_approx(x^3 - x - 1, CC.gen())
-0.6623589786223730? + 0.5622795120623013?*I

sage: root_from_approx(x^2 + 1, 0)
Traceback (most recent call last):
...
ValueError: x^2 + 1 has no real roots
sage: root_from_approx(x^2 + 1, CC(0))
-1*I

sage: root_from_approx(x^2 - 2, sqrt(2))
sqrt(2)
sage: root_from_approx(x^2 - 2, sqrt(3))
Traceback (most recent call last):
...
ValueError: sqrt(3) is not a root of x^2 - 2