Adapt QQBar documentation (#1715)

Co-authored-by: Max Horn <[email protected]>

docs/src/algebraic.md

@@ -10,23 +10,13 @@ end
 Nemo allows working with exact real and complex algebraic numbers.
 
 The default algebraic number type in Nemo is provided by Calcium. The
-associated field of algebraic numbers is represented by the constant
-parent object called `CalciumQQBar`.
+associated field of algebraic numbers can be constructed using
+`QQBar = algebraic_closure(QQ)`. We will leave out this line from
+all code blocks on this page for brevity.
 
-For convenience we define
-
-```
-QQBar = CalciumQQBar
-```
-
-so that algebraic numbers can be constructed using `QQBar` instead of
-`CalciumQQBar`. Note that this is the name of a specific parent object,
-not the name of its type.
-
-
- Library        | Element type  | Parent type
-----------------|---------------|--------------------
-Calcium         | `QQBarFieldElem`       | `QQBarField`
+ Library        | Element type     | Parent type
+----------------|------------------|--------------------
+Calcium         | `QQBarFieldElem` | `QQBarField`
 
 **Important note on performance**
 
@@ -38,8 +28,7 @@ For fast calculation in $\overline{\mathbb{Q}}$,
 `CalciumField` should typically be used instead (see the section
 on *Exact real and complex numbers*).
 Alternatively, to compute in a fixed subfield of $\overline{\mathbb{Q}}$,
-you may fix a generator $a$ and construct an
-Antic number field to represent $\mathbb{Q}(a)$.
+you may fix a generator $a$ and construct a number field to represent $\mathbb{Q}(a)$.
 
 ## Algebraic number functionality
 
@@ -58,7 +47,7 @@ Methods to construct algebraic numbers include:
 
 Arithmetic:
 
-```jldoctest
+```jldoctest; setup = :(QQBar = algebraic_closure(QQ))
 julia> ZZRingElem(QQBar(3))
 3
 
@@ -71,7 +60,7 @@ Root 0.500000 + 0.866025*im of x^2 - x + 1
 
 Solving the quintic equation:
 
-```jldoctest
+```jldoctest; setup = :(QQBar = algebraic_closure(QQ))
 julia> R, x = polynomial_ring(QQ, "x")
 (Univariate polynomial ring in x over QQ, x)
 
@@ -89,7 +78,7 @@ true
 
 Computing exact eigenvalues of a matrix:
 
-```jldoctest
+```jldoctest; setup = :(QQBar = algebraic_closure(QQ))
 julia> eigenvalues(QQBar, ZZ[1 1 0; 0 1 1; 1 0 1])
 3-element Vector{QQBarFieldElem}:
  Root 2.00000 of x - 2
@@ -117,7 +106,7 @@ Algebraic numbers can be evaluated
 numerically to arbitrary precision by converting
 to real or complex Arb fields:
 
-```jldoctest
+```jldoctest; setup = :(QQBar = algebraic_closure(QQ))
 julia> RR = ArbField(64); RR(sqrt(QQBar(2)))
 [1.414213562373095049 +/- 3.45e-19]
 
@@ -132,7 +121,7 @@ julia> CC = AcbField(32); CC(QQBar(-1) ^ (QQBar(1) // 4))
 Retrieving the minimal polynomial and algebraic conjugates
 of a given algebraic number:
 
-```jldoctest
+```jldoctest; setup = :(QQBar = algebraic_closure(QQ))
 julia> minpoly(polynomial_ring(ZZ, "x")[1], QQBar(1+2im))
 x^2 - 2*x + 5
 
@@ -165,7 +154,7 @@ height_bits(x::QQBarFieldElem)
 
 **Examples**
 
-```jldoctest
+```jldoctest; setup = :(QQBar = algebraic_closure(QQ))
 julia> real(sqrt(QQBar(1im)))
 Root 0.707107 of 2x^2 - 1
 
@@ -223,7 +212,7 @@ first.
 
 **Examples**
 
-```jldoctest
+```jldoctest; setup = :(QQBar = algebraic_closure(QQ))
 julia> 1 < sqrt(QQBar(2)) < QQBar(3)//2
 true
 
@@ -260,7 +249,7 @@ is_less_root_order(a::QQBarFieldElem, b::QQBarFieldElem)
 
 **Examples**
 
-```jldoctest
+```jldoctest; setup = :(QQBar = algebraic_closure(QQ))
 julia> root(QQBar(2), 5)
 Root 1.14870 of x^5 - 2
 
@@ -315,7 +304,7 @@ atanpi(a::QQBarFieldElem)
 
 An algebraic number can be recovered from a numerical value:
 
-```jldoctest
+```jldoctest; setup = :(QQBar = algebraic_closure(QQ))
 julia> RR = RealField(); guess(QQBar, RR("1.41421356 +/- 1e-6"), 2)
 Root 1.41421 of x^2 - 2
 ```
@@ -325,7 +314,7 @@ approximation, you should add an error estimate; otherwise, at best the only
 algebraic number that can be guessed is the binary floating-point number
 itself, at worst no guess is possible.
 
-```jldoctest
+```jldoctest; setup = :(QQBar = algebraic_closure(QQ))
 julia> RR = RealField();
 
 julia> x = RR(0.1)       # note: 53-bit binary approximation of 1//10 without radius

docs/src/exact.md

@@ -151,7 +151,7 @@ x^4 + -10*x^2 + 1
 ## Conversions and numerical evaluation
 
 Calcium numbers can created from integers (`ZZ`), rationals (`QQ`)
-and algebraic numbers (`QQbar`), and through the application of
+and algebraic numbers (`algebraic_closure(QQ)`), and through the application of
 arithmetic operations and transcendental functions.
 
 Calcium numbers can be converted to integers, rational and algebraic fields
@@ -165,7 +165,7 @@ value because of evaluation limits.
 julia> QQ(C(1))
 1
 
-julia> QQBar(sqrt(C(2)) // 2)
+julia> algebraic_closure(QQ)(sqrt(C(2)) // 2)
 Root 0.707107 of 2x^2 - 1
 
 julia> QQ(C(pi))

src/Deprecations.jl

@@ -75,3 +75,9 @@ end
 is_power(x::IntegerUnion) = is_perfect_power_with_data(x)
 is_power(x::QQFieldElem) = is_perfect_power_with_data(x)
 is_power(x::Rational) = is_perfect_power_with_data(x)
+
+const QQBar = QQBarField()
+export QQBar
+
+const CalciumQQBar = QQBarField()
+export CalciumQQBar

src/Exports.jl

@@ -63,7 +63,6 @@ export bits
 export bound_inf_norm
 export CalciumField
 export CalciumFieldElem
-export CalciumQQBar
 export canonical_unit
 export cdiv
 export cdivpow2
@@ -502,7 +501,6 @@ export QadicFieldElem
 export QQ
 export QQAbsPowerSeriesRing
 export QQAbsPowerSeriesRingElem
-export QQBar
 export QQBarField
 export QQBarFieldElem
 export QQField

src/Nemo.jl

@@ -592,16 +592,6 @@ const FlintQQ = QQ
 GaussianIntegers() = FlintZZi
 GaussianRationals() = FlintQQi
 
-###############################################################################
-#
-#   Set domain for QQBar to Calcium
-#
-###############################################################################
-
-@doc qqbar_field_doc
-const QQBar = CalciumQQBar
-
-
 ###############################################################################
 #
 #   Some explicit type piracy against AbstractAlgebra

src/calcium/CalciumTypes.jl

@@ -86,8 +86,6 @@ Root 0.866025 of 4x^2 - 3
 struct QQBarField <: Field
 end
 
-const CalciumQQBar = QQBarField()
-
 @doc qq_field_doc
 mutable struct QQBarFieldElem <: FieldElem
   coeffs::Ptr{Nothing}

src/calcium/ca.jl

@@ -1482,7 +1482,7 @@ end
 
 # todo: optimize
 function (C::CalciumField)(v::Complex{Int})
-  return C(QQBar(v))
+  return C(QQBarFieldElem(v))
 end
 
 function (C::CalciumField)(x::Irrational)

src/calcium/qqbar.jl

@@ -10,7 +10,7 @@
 #
 ###############################################################################
 
-parent(a::QQBarFieldElem) = CalciumQQBar
+parent(a::QQBarFieldElem) = QQBarField()
 
 parent_type(::Type{QQBarFieldElem}) = QQBarField
 
@@ -178,9 +178,9 @@ zero(a::QQBarField) = a(0)
 
 one(a::QQBarField) = a(1)
 
-zero(::Type{QQBarFieldElem}) = CalciumQQBar(0)
+zero(::Type{QQBarFieldElem}) = QQBarFieldElem(0)
 
-one(::Type{QQBarFieldElem}) = CalciumQQBar(1)
+one(::Type{QQBarFieldElem}) = QQBarFieldElem(1)
 
 @doc raw"""
     degree(x::QQBarFieldElem)
@@ -1176,7 +1176,9 @@ Throws if this value is transcendental.
 # Examples
 
 ```jldoctest
-julia> x = sinpi(QQBar(1)//3)
+julia> QQBar = algebraic_closure(QQ);
+
+julia> x = sinpi(QQBar(1//3))
 Root 0.866025 of 4x^2 - 3
 
 julia> sinpi(x)
@@ -1202,7 +1204,9 @@ Throws if this value is transcendental.
 # Examples
 
 ```jldoctest
-julia> x = cospi(QQBar(1)//6)
+julia> QQBar = algebraic_closure(QQ);
+
+julia> x = cospi(QQBar(1//6))
 Root 0.866025 of 4x^2 - 3
 
 julia> cospi(x)
@@ -1228,7 +1232,9 @@ Throws if either value is transcendental.
 # Examples
 
 ```jldoctest
-julia> s, c = sincospi(QQBar(1)//3)
+julia> QQBar = algebraic_closure(QQ);
+
+julia> s, c = sincospi(QQBar(1//3))
 (Root 0.866025 of 4x^2 - 3, Root 0.500000 of 2x - 1)
 
 julia> sincospi(s)
@@ -1547,4 +1553,4 @@ julia> sqrt(K(2))
 Root 1.41421 of x^2 - 2
 ```
 """
-algebraic_closure(::QQField) = QQBar
+algebraic_closure(::QQField) = QQBarField()

test/calcium/ca-test.jl

@@ -237,6 +237,7 @@ end
 
 @testset "CalciumFieldElem.conversions" begin
   C = CalciumField()
+  R = algebraic_closure(QQ)
 
   n = C(3)
   h = C(1) // 2
@@ -248,9 +249,9 @@ end
   @test QQ(h) == QQFieldElem(1) // 2
   @test_throws ErrorException ZZ(h)
 
-  @test CalciumQQBar(h) == QQBarFieldElem(1) // 2
-  @test CalciumQQBar(c) == QQBarFieldElem(1+2im)
-  @test_throws ErrorException CalciumQQBar(t)
+  @test R(h) == QQBarFieldElem(1) // 2
+  @test R(c) == QQBarFieldElem(1+2im)
+  @test_throws ErrorException R(t)
 
   RR = ArbField(64)
   CC = AcbField(64)