added missing function headers

functions.jl

@@ -58,6 +58,13 @@ function newtoninversion(f::PolyElem, l::Int, k::Int)
     g
 end
 
+"""
+    newtoninversion(f::PolyElem, l::Int; validation::Bool=false)
+
+Invert the polynomial f through a Newton iteration such that fg=1 mod y^l mod x^{k}
+works for f(0) a nonzero constant
+if validation = true, validate and bound the numeric result after computation. 
+"""
 function newtoninversion(f::PolyElem, l::Int; validation::Bool=false)
     if (validation)
         ff = convert_balls_to_Float(f)
@@ -80,6 +87,13 @@ function newtoninversion(f::PolyElem, l::Int; validation::Bool=false)
     g
 end
 
+"""
+    newtoninversion(f::PolyElem, l::Int, k::Int; validation::Bool =false)
+
+Invert the polynomial f through a Newton iteration such that fg=1 mod y^l mod x^{k}
+works for f(0) a nonzero constant
+if validation = true, validate and bound the numeric result after computation. 
+"""
 function newtoninversion(f::PolyElem, l::Int, k::Int; validation::Bool =false)
     if (validation)
         ff = convert_balls_to_Float(f)
@@ -160,6 +174,13 @@ function fastdivrem(a::PolyElem, b::PolyElem)
     q, r, invrevb
 end
 
+"""
+    fastdivrem(a::PolyElem, b::PolyElem; validation::Bool = false)
+
+Divide polynomial a by polynomial b with remainder and return q and r such that a = q*b + r.
+b has to be monic.
+If validation = true, validate and bound the numeric result of the substeps.
+"""
 function fastdivrem(a::PolyElem, b::PolyElem; validation::Bool = false)
     da = degree(a)
     db = degree(b)
@@ -178,6 +199,13 @@ function fastdivrem(a::PolyElem, b::PolyElem; validation::Bool = false)
     q, r, invrevb
 end
 
+"""
+    fastdivrem(a::PolyElem, b::PolyElem, k::Int; validation::Bool = false)
+
+Divide polynomial a by polynomial b with remainder and return q and r such that a = q*b + r.
+b has to be monic.
+If validation = true, validate and bound the numeric result of the substeps.
+"""
 function fastdivrem(a::PolyElem, b::PolyElem, k::Int; validation::Bool = false)
     da = degree(a)
     db = degree(b)
@@ -193,6 +221,13 @@ function fastdivrem(a::PolyElem, b::PolyElem, k::Int; validation::Bool = false)
     (q,r)
 end
 
+"""
+    fastdivrem_validated(ai::arb_poly, bi::arb_poly)
+
+Divide polynomial a by polynomial b with remainder and return q and r such that a = q*b + r.
+b has to be monic.
+If validation = true, validate and bound the numeric result of the substeps.
+"""
 function fastdivrem_validated(ai::arb_poly, bi::arb_poly)
     da = degree(ai)
     db = degree(bi)
@@ -213,6 +248,13 @@ function fastdivrem_validated(ai::arb_poly, bi::arb_poly)
     (q,r)
 end
 
+"""
+    fastdivrem_validated_bivariate(ai::PolyElem{T}, bi::PolyElem{T}, k::Int) where T <: arb_poly
+
+Divide polynomial a by polynomial b with remainder and return q and r such that a = q*b + r.
+b has to be monic.
+If validation = true, validate and bound the numeric result of the substeps.
+"""
 function fastdivrem_validated_bivariate(ai::PolyElem{T}, bi::PolyElem{T}, k::Int) where T <: arb_poly
     da = degree(ai)
     db = degree(bi)
@@ -291,6 +333,17 @@ function henseltruncate(l::Int, f::PolyElem, g::PolyElem, h::PolyElem, s::PolyEl
     (g,h,s,t)
 end
 
+"""
+    henseltruncate(l::Int, f::PolyElem, g::PolyElem, h::PolyElem; validation::Bool = false)
+
+Do a Hensel lifting on the polynomials g and h  such that f ≡ g* h* mod x^l
+
+# Arguments
+- `g, h` need to be given such that f≡gh mod x
+- `h` is monic
+- `l` power of two
+If validation = true, validate and bound the numeric result of the substeps.
+"""
 function henseltruncate(l::Int, f::PolyElem, g::PolyElem, h::PolyElem; validation::Bool = false)
     deg = 1
     (_,s,t) = gcdx(g,h)
@@ -302,12 +355,18 @@ function henseltruncate(l::Int, f::PolyElem, g::PolyElem, h::PolyElem; validatio
     (g,h,s,t)
 end
 
+"""
+    hensel_validate(l::Int, f::PolyElem, g::PolyElem, h::PolyElem; ϵ=1e-10, imax = 20)
+
+Compute Hensel in Float64 polynomials and validate and bound the result a posteriori
+"""
 function hensel_validate(l::Int, f::PolyElem, g::PolyElem, h::PolyElem; ϵ=1e-10, imax = 20)
     dg = degree(g)
     dh = degree(h)
     df = degree(f)
     @show dg
     @show dh
+
     #convert input polynomials to real polynomials in Float64
     gr = convert_balls_to_Float(g)
     hr = convert_balls_to_Float(h)
@@ -567,6 +626,15 @@ function validate_a_posteriori_inverse(q::PolyElem{T}, b::PolyElem{S}; ϵ = 1e-1
     (r, tmax, string("no convergence in ", tmax, " steps, last r = ", r))
 end
 
+"""
+    validate_a_posteriori_inverse_bivariate(q::PolyElem{T}, b::PolyElem{S}, trunc::Int; ϵ = 1e-10, tmax = 20) where {T <: PolyElem, S<: PolyElem}
+
+A posteriori validation of a numerical solution q to qb-1 = 0 mod y^(degree(b)+1)
+Returns coefficientwise error bounds for q in the form of a polynomial.
+# Arguments 
+- `q` approximate solution to qb-1 = 0 mod y^(degree(b)+1), float-valued polynomial
+- `b` interval valued polynomial 
+"""
 function validate_a_posteriori_inverse_bivariate(q::PolyElem{T}, b::PolyElem{S}, trunc::Int; ϵ = 1e-10, tmax = 20) where {T <: PolyElem, S<: PolyElem}
     db = degree(b)
     q_rig = convert_float_to_balls(q)
@@ -619,130 +687,3 @@ function validate_a_posteriori_inverse_bivariate(q::PolyElem{T}, b::PolyElem{S},
     print("no convergence in ", tmax, " steps, last r = ", r, "\n")
     (r, tmax, string("no convergence in ", tmax, " steps"))
 end
-
-#=function validate_a_posteriori_fastdivrem(a::PolyElem{T}, b::PolyElem{T}, q::PolyElem{T}, binv::PolyElem{T}, ai::arb_poly, bi::arb_poly; ϵ = 1e-10, tmax = 20) where T
-    k = degree(q)
-    #=if T<:PolyElem
-        d = zeros(Int,k+1)
-        for i ∈ 1:k+1
-            @show coeff(q,i-1)
-            d[i] = degree(coeff(q,i-1))
-        end
-        trunc = maximum(d)+1
-        @show trunc
-    end=#
-    η = 1 - mullow(binv,rev(b,degree(b)+1),k+1)
-    η = abs_coefficientwise!(η)
-    δ = mullow(binv, mullow(rev(q,k+1), rev(b,degree(b)+1), k+1)-rev(a,degree(a)+1), k+1)
-    δ = abs_coefficientwise!(δ)
-    δmin = nonzeroMin(δ)
-    for i ∈ 1:k+1
-        if (coeff(δ, i-1)== 0)
-            set_coefficient!(δ,i-1, δmin)            
-        end
-    end
-    #=if T <: PolyElem
-        BivPolMod!(η,trunc +1)
-        BivPolMod!(δ,trunc +1)   
-    end=#
-    @show δ
-    e = ϵ .* δ 
-    δ_plus = δ + e
-    r = parent(q)(0)
-    for t ∈ 0:tmax
-        rr = mullow(η, r, k+1) + δ_plus
-        #=if T <: PolyElem
-            BivPolMod!(rr, trunc +1)
-        end=#
-        diff = rr-r
-        abs_coefficientwise!(diff)
-        if isless(diff,e)
-            return (rev(r,k+1),t)            
-        end
-        r = rr
-    end
-    print("no convergence in ", tmax, " steps, last r = ", r, "\n")
-    (string("no convergence in ", tmax, " steps, last r = ", r, "\n"),tmax)
-end=#
-
-#="""
-    validate_a_posteriori_fastdivrem(a::PolyElem{T}, b::PolyElem{T}, q::PolyElem{T}, binv::PolyElem{T}; ϵ = 1e-10, tmax = 20) where T
-
-A posteriori validation to a numerical solution q of bq-a = 0 mod x^{k+1}
-Returns coefficientwise error bounds for q in the form of a polynomial.
-"""
-function validate_a_posteriori_fastdivrem(a::PolyElem{T}, b::PolyElem{T}, q::PolyElem{T}, binv::PolyElem{T}, ai::PolyElem{S}, bi::PolyElem{S}; ϵ = 1e-10, tmax = 20) where {T, S <: Union{arb_poly, PolyElem{arb_poly}}}
-    k = degree(q)
-    #=if T<:PolyElem
-        d = zeros(Int,k+1)
-        for i ∈ 1:k+1
-            @show coeff(q,i-1)
-            d[i] = degree(coeff(q,i-1))
-        end
-        trunc = maximum(d)+1
-        @show trunc
-    end=#
-    
-    #rigorous starting functions
-    a_rig = ai
-    b_rig = bi
-    q_rig = convert_float_to_balls(q)
-    binv_rig = convert_float_to_balls(binv)
-
-    #compute η and δ
-    #where |N(x)-N(x')| <= η |x-x'|
-    #and δ >= |N(x)-x|
-
-    #η = 1 - mullow(binv,rev(b,degree(b)+1),k+1)
-    η = 1 - mullow(binv_rig, rev(b_rig,degree(b_rig)+1),k+1)
-    η = abs_coefficientwise!(η)
-    η = mag_coefficientwise(η)
-    #δ = mullow(binv, mullow(rev(q,k+1), rev(b,degree(b)+1), k+1)-rev(a,degree(a)+1), k+1)
-    δ = mullow(binv_rig, mullow(rev(q_rig,k+1), rev(b_rig,degree(b_rig)+1), k+1)-rev(a_rig,degree(a_rig)+1), k+1)
-    δ = abs_coefficientwise!(δ)
-    δ = mag_coefficientwise(δ)
-
-    #replace zero coefficients by nonzero coefficients
-    #TODO: adapt this part for bivariate polynomials
-    δmin = nonzeroMin(δ)
-    for i ∈ 1:k+1
-        if T <: PolyElem
-            ki = degree(coeff(b,i)) #le maximum des ki? ou je dois introduir quelque part notre n de mod x^n
-            for j ∈ 1:ki+1
-                if (coeff(coeff(δ,i-1),j-1)== 0)
-                    set_coefficient!(δ.coeffs[i],j-1, δmin)
-                end
-            end
-        else
-            if (coeff(δ, i-1)== 0)
-                set_coefficient!(δ,i-1, δmin)            
-            end
-        end
-    end
-    #=if T <: PolyElem
-        BivPolMod!(η,trunc +1)
-        BivPolMod!(δ,trunc +1)   
-    end=#
-
-    @show δ
-    e = ϵ * δ 
-    δ_plus = δ + e
-    r = parent(η)(0)
-    for t ∈ 0:tmax
-        rr = mullow(η, r, k+1) + δ_plus
-        rr = mag_coefficientwise(rr)
-        #=if T <: PolyElem
-            BivPolMod!(rr, trunc +1)
-        end=#
-        diff = rr-r
-        abs_coefficientwise!(diff)
-        if isless_coefficientwise(diff,e)
-            return (rev(r,k+1),t)            
-        end
-        r = rr
-    end
-    print("no convergence in ", tmax, " steps, last r = ", r, "\n")
-    (string("no convergence in ", tmax, " steps, last r = ", r, "\n"),tmax)
-end=#
-
-

practicalfunctions.jl

@@ -33,6 +33,12 @@ function isless_coefficientwise(p::PolyElem{S},q::PolyElem{T}) where {S <: Union
     return true
 end
 
+"""
+    isless_coefficientwise(p::PolyElem{S},q::PolyElem{T}) where {S <: PolyElem, T <: PolyElem}
+
+Return true if all coefficients of p are smaller than their corresponding coefficient of q.
+Return false else.
+"""
 function isless_coefficientwise(p::PolyElem{S},q::PolyElem{T}) where {S <: PolyElem, T <: PolyElem}
     print("isless()\n")
     d = max(degree(p), degree(q))
@@ -49,6 +55,12 @@ function isless_coefficientwise(p::PolyElem{S},q::PolyElem{T}) where {S <: PolyE
     return true
 end
 
+"""
+    isless_coefficientwise(p::PolyElem{T},q::PolyElem{T}) where T <: arb_poly
+
+Return true if all coefficients of p are smaller than their corresponding coefficient of q.
+Return false else.
+"""
 function isless_coefficientwise(p::PolyElem{T},q::PolyElem{T}) where T <: arb_poly
     d = max(degree(p), degree(q))
     for i in 1:d+1
@@ -119,6 +131,11 @@ function nonzeroMin(d::PolyElem{T}) where T <: Union{FieldElem, AbstractFloat}
     min
 end
 
+"""
+    range_of_coefficients(p::PolyElem{T}) where T
+
+Return the smallest (nonzero) and highest absolute value of the coefficients of p
+"""
 function range_of_coefficients(p::PolyElem{T}) where T
     dp = degree(p)
     min = 0.0
@@ -142,17 +159,11 @@ function range_of_coefficients(p::PolyElem{T}) where T
     (min,max)
 end
 
-#=
-function multiply(p::PolyElem{T},q::PolyElem{T}) where T <: Union{PolyRingElem{ArbField}, PolyRingElem{RealField}}
-
-    
-end
-
-function kronecker_evaluation(p::PolyElem)
-
-end
-=#
+"""
+    convert_float_to_balls(p::PolyElem{T}) where T <: PolyElem
 
+Convert a real polynomial p to a polynomial with thin intervals around the coefficients of p.
+"""
 function convert_float_to_balls(p::PolyElem{T}) where T <: PolyElem
     dp = degree(p)
     RR = ArbField(53)
@@ -166,6 +177,11 @@ function convert_float_to_balls(p::PolyElem{T}) where T <: PolyElem
     q
 end
 
+"""
+    convert_float_to_balls(p::PolyElem{T})  where T<:Union{AbstractFloat, FieldElem}
+
+Convert a real polynomial p to a polynomial with thin intervals around the coefficients of p.
+"""
 function convert_float_to_balls(p::PolyElem{T})  where T<:Union{AbstractFloat, FieldElem}
     dp = degree(p)
     RR = ArbField(53)
@@ -179,6 +195,11 @@ function convert_float_to_balls(p::PolyElem{T})  where T<:Union{AbstractFloat, F
     q
 end
 
+"""
+    convert_balls_to_Float(p::PolyElem{T}; rounding = RoundNearest) where T
+
+Convert a polynomial p with interval coefficients into a polynomial with real coefficients. By definition the coefficients will be the interval midpoints, but with changes to the rounding methods, it can also return the upper bound or lower bound values of p.
+"""
 function convert_balls_to_Float(p::PolyElem{T}; rounding = RoundNearest) where T
     dp = degree(p)
     RX, _ = PolynomialRing(RDF, "x")
@@ -210,11 +231,21 @@ function convert_balls_to_lowerBound_Float(p::PolyElem{T}) where T
     convert_balls_to_Float(p,rounding = RoundDown)
 end
 
+"""
+    mag(a::T) where T <: Union{arb,acb}
+
+Return max(abs(a))
+"""
 function mag(a::T) where T <: Union{arb,acb}
     m = abs(a)
     m = RR(Float64(m, RoundUp))
 end
 
+"""
+    mag_coefficientwise(p::PolyElem{T}) where T
+
+Apply max(abs(*)) on each coefficient of p.
+"""
 function mag_coefficientwise(p::PolyElem{T}) where T
     dp = degree(p)
     RR = ArbField(53)
@@ -240,6 +271,11 @@ function printpoly(p::PolyElem)
     @show convert_balls_to_upperBound_Float(p)
 end
 
+"""
+    comparepoly(p::PolyElem{T}, q::PolyElem{T}) where T <:Union{arb,arb_poly}
+
+Prints indexes and corresponding coefficients of p and q in a line each.
+"""
 function comparepoly(p::PolyElem{T}, q::PolyElem{T}) where T <:Union{arb,arb_poly}
     d = max(degree(p), degree(q))
     if T <: PolyElem
@@ -258,6 +294,11 @@ function comparepoly(p::PolyElem{T}, q::PolyElem{T}) where T <:Union{arb,arb_pol
     end
 end
 
+"""
+    comparepoly(p::PolyElem{T}, q::PolyElem{S}) where {T,S}
+
+Prints indexes and corresponding coefficients of p and q in a line each.
+"""
 function comparepoly(p::PolyElem{T}, q::PolyElem{S}) where {T,S}
     d = max(degree(p), degree(q))
     if T <: PolyElem
@@ -280,6 +321,11 @@ function sub(q,p)
     end
 end
 
+"""
+    subs(q::PolyElem{T},p::PolyElem) where {T<:Union{PolyElem,AbstractFloat}}
+
+Subtract a polynomial p with rational coefficients from a polynomial q with real coefficients.
+"""
 function subs(q::PolyElem{T},p::PolyElem) where {T<:Union{PolyElem,AbstractFloat}}
     d = max(degree(q),degree(p))
     FB = Nemo.AbstractAlgebra.Floats{BigFloat}()
@@ -300,6 +346,12 @@ function subs(q::PolyElem{T},p::PolyElem) where {T<:Union{PolyElem,AbstractFloat
     r
 end
 
+"""
+    convert_polynomial(p::PolyElem{T},listOfRings, coeff_field) where {T <: Union{QQPolyRingElem,QQFieldElem}}
+
+Convert a polynomial with rational coefficients to a polynomial with coefficients in coeff_field.
+listOfRings includes an array of polynomial rings the polynomial should be converted to, starting with the outermost ring, followed by the polynomial ring of its coefficients, etc.
+"""
 function convert_polynomial(p::PolyElem{T},listOfRings, coeff_field) where {T <: Union{QQPolyRingElem,QQFieldElem}}
     d = degree(p)
     q = (listOfRings[1])(0)
@@ -319,6 +371,11 @@ function convert_polynomial(p::PolyElem{T},listOfRings, coeff_field) where {T <:
     q
 end
 
+"""
+    convert_polynomial_to_intervals(p::PolyElem{T},r::PolyElem{T}) where T
+
+Return a polynomial with interval valued coefficients, whose coefficients are intervals around the coefficients of p with the radius being the coefficients of r.
+"""
 function convert_polynomial_to_intervals(p::PolyElem{T},r::PolyElem{T}) where T
     d = max(degree(p),degree(r))
     RR = ArbField(53)
@@ -342,6 +399,11 @@ function convert_polynomial_to_intervals(p::PolyElem{T},r::PolyElem{T}) where T
     pi
 end
 
+"""
+    extract_radius(p::PolyElem{T}) where T
+
+Return a polynomial whose coefficients are the radii of the coefficients of the input polynomial p.
+"""
 function extract_radius(p::PolyElem{T}) where T
     r = parent(p)(0)
     d = degree(p)
@@ -355,6 +417,11 @@ function extract_radius(p::PolyElem{T}) where T
     r
 end
 
+"""
+    replace_zeros!(p::PolyElem{T}, d, dp = -1, k = -1) where T
+
+Replaces zero coefficients in polynomial p by the value d, dp being the wanted degree of the output polynomial, and k the degree of the coefficients for bivariate input polynomials.
+"""
 function replace_zeros!(p::PolyElem{T}, d, dp = -1, k = -1) where T
     if (T <: PolyElem)&&(dp == -1)
         deg = degree(p)