From 57f93b2213037afbf3069698b58e76075b60a7de Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Thu, 25 Apr 2024 11:40:47 +0000 Subject: [PATCH] build based on 4f79faa --- dev/.documenter-siteinfo.json | 2 +- dev/index.html | 2 +- dev/interface-ball/index.html | 6 +-- dev/interface-integration/index.html | 4 +- dev/interface-mutable/index.html | 64 ++++++++++++++-------------- dev/interface-series/index.html | 2 +- dev/interface-types/index.html | 10 ++--- dev/rigorous/index.html | 2 +- dev/wrapper-fpwrap/index.html | 4 +- dev/wrapper-methods/index.html | 4 +- dev/wrapper-types/index.html | 4 +- 11 files changed, 52 insertions(+), 52 deletions(-) diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 21aa7a0..9313e26 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.2","generation_timestamp":"2024-04-22T11:46:47","documenter_version":"1.4.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.2","generation_timestamp":"2024-04-25T11:40:44","documenter_version":"1.4.0"}} \ No newline at end of file diff --git a/dev/index.html b/dev/index.html index 025ebd3..8d7e79a 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Arblib.jl Documentation · Arblib.jl
GitHub

Arblib.jl Documentation

This package is a wrapper around Arb - a C library for arbitrary-precision ball arithmetic. Since 2023 Arb is part of Flint. Other wrappers of Arb/Flint for Julia include Nemo and ArbNumerics.jl.

The goal of Arblib.jl is to supply a low lever wrapper of the methods in Arb as well as a high level interface. The low level wrapper should allow for writing methods using mutability and with performance very close to that of those written in C. The high level interface should make it easy to use in generic Julia code, similarly to how BigFloat is a wrapper around the MPFR library. In addition it should be possible to seamlessly switch between the high level interface and the low level wrapper when needed.

The above goals can be put into contrast with Nemo, whose high level interface is made for use in the AbstractAlgebra.jl universe and not general Julia code.

+Arblib.jl Documentation · Arblib.jl
GitHub

Arblib.jl Documentation

This package is a wrapper around Arb - a C library for arbitrary-precision ball arithmetic. Since 2023 Arb is part of Flint. Other wrappers of Arb/Flint for Julia include Nemo and ArbNumerics.jl.

The goal of Arblib.jl is to supply a low lever wrapper of the methods in Arb as well as a high level interface. The low level wrapper should allow for writing methods using mutability and with performance very close to that of those written in C. The high level interface should make it easy to use in generic Julia code, similarly to how BigFloat is a wrapper around the MPFR library. In addition it should be possible to seamlessly switch between the high level interface and the low level wrapper when needed.

The above goals can be put into contrast with Nemo, whose high level interface is made for use in the AbstractAlgebra.jl universe and not general Julia code.

diff --git a/dev/interface-ball/index.html b/dev/interface-ball/index.html index b335fe0..8d353c6 100644 --- a/dev/interface-ball/index.html +++ b/dev/interface-ball/index.html @@ -1,7 +1,7 @@ -Ball methods · Arblib.jl
GitHub

Ball methods

The following methods are useful for explicitly dealing with the ball representation of Arb and related values.

Construction

For constructing balls the methods below are useful. Note that there is no setinterval method, this is instead accomplished with Arb((a, b)) for constructing a ball containing the interval $[a, b]$.

Arblib.setball — Function
setball(::Type{Arb}, m, r; prec = _precision(m))

Returns an Arb with the midpoint and radius set to m and r respectively.

Note that the m is converted to an Arf and therefore rounded. So for example setball(1 // 3, 0) will not contain $1 / 3$.

See also getball and add_error.

source
Arblib.add_error — Function
add_error(x, err)

Returns a copy of x with the absolute value of err added to the radius.

For complex x it adds the error to both the real and imaginary parts. For matrices it adds it elementwise.

See also setball.

source

Destruction

For extracting information about the ball representation the following methods are useful.

Arblib.radius — Function
radius([T, ] x::ArbOrRef)

Returns the radius of x as a Mag. If T is given convert to this type, supports Mag, Arf, Arb and Float64.

source
Arblib.midpoint — Function
midpoint([T, ] x::ArbOrRef)

Returns the midpoint of x as an Arf. If T is given convert to this type, supports Arf and Arb.

source
midpoint([T, ] z::AcbOrRef)

Returns the midpoint of z as a Complex{Arf}. If T is given and equal to Arf or Arb, convert to Complex{T}. If T is Acb then convert to that.

source
Arblib.lbound — Function
lbound([T, ] x::ArbOrRef)

Returns a lower bound of x as an Arf. If T is given convert to this type, supports Arf and Arb.

If x contains NaN it returns NaN.

source
Arblib.ubound — Function
ubound([T, ] x::ArbOrRef)

Returns an upper bound of x as an Arf. If T is given convert to this type, supports Arf and Arb.

If x contains NaN it returns NaN.

source
Arblib.abs_lbound — Function
abs_lbound([T, ] x::Union{ArbOrRef,AcbOrRef})

Returns a lower bound of abs(x) as an Arf. If T is given convert to this type, supports Arf and Arb.

If x contains NaN it returns NaN.

source
Arblib.abs_ubound — Function
abs_ubound([T, ] x::Union{ArbOrRef,AcbOrRef})

Returns an upper bound of abs(x) as an Arf. If T is given convert to this type, supports Arf and Arb.

If x contains NaN it returns NaN.

source
Arblib.getinterval — Function
getinterval([T, ] x::ArbOrRef)

Returns a tuple (l, u) representing an interval [l, u] enclosing the ball x, both of them are of type Arf. If T is given convert to this type, supports Arf, BigFloat and Arb.

If x contains NaN both l and u will be NaN.

See also getball.

source
Arblib.getball — Function
getball([T, ] x::ArbOrRef)

Returns a tuple (m::Arf, r::Mag) where m is the midpoint of the ball and r is the radius. If T is given convert both m and r to this type, supports Arf and Arb.

See also setball and getinterval.

source

Union and intersection

The methods Arblib.union and Arblib.intersection compute the union and intersection of balls. Note that these methods are not exported and different from Base.union and Base.intersect.

Arblib.union — Function
union(x::ArbOrRef, y::ArbOrRef)
+Ball methods · Arblib.jl
GitHub
Ball methods
The following methods are useful for explicitly dealing with the ball representation of Arb and related values.
Construction
For constructing balls the methods below are useful. Note that there is no setinterval method, this is instead accomplished with Arb((a, b)) for constructing a ball containing the interval $[a, b]$.
Arblib.setball — Function
setball(::Type{Arb}, m, r; prec = _precision(m))
Returns an Arb with the midpoint and radius set to m and r respectively.
Note that the m is converted to an Arf and therefore rounded. So for example setball(1 // 3, 0) will not contain $1 / 3$.
See also getball and add_error.
source
Arblib.add_error — Function
add_error(x, err)
Returns a copy of x with the absolute value of err added to the radius.
For complex x it adds the error to both the real and imaginary parts. For matrices it adds it elementwise.
See also setball.
source
Destruction
For extracting information about the ball representation the following methods are useful.
Arblib.radius — Function
radius([T, ] x::ArbOrRef)
Returns the radius of x as a Mag. If T is given convert to this type, supports Mag, Arf, Arb and Float64.
source
Arblib.midpoint — Function
midpoint([T, ] x::ArbOrRef)
Returns the midpoint of x as an Arf. If T is given convert to this type, supports Arf and Arb.
source
midpoint([T, ] z::AcbOrRef)
Returns the midpoint of z as a Complex{Arf}. If T is given and equal to Arf or Arb, convert to Complex{T}. If T is Acb then convert to that.
source
Arblib.lbound — Function
lbound([T, ] x::ArbOrRef)
Returns a lower bound of x as an Arf. If T is given convert to this type, supports Arf and Arb.
If x contains NaN it returns NaN.
source
Arblib.ubound — Function
ubound([T, ] x::ArbOrRef)
Returns an upper bound of x as an Arf. If T is given convert to this type, supports Arf and Arb.
If x contains NaN it returns NaN.
source
Arblib.abs_lbound — Function
abs_lbound([T, ] x::Union{ArbOrRef,AcbOrRef})
Returns a lower bound of abs(x) as an Arf. If T is given convert to this type, supports Arf and Arb.
If x contains NaN it returns NaN.
source
Arblib.abs_ubound — Function
abs_ubound([T, ] x::Union{ArbOrRef,AcbOrRef})
Returns an upper bound of abs(x) as an Arf. If T is given convert to this type, supports Arf and Arb.
If x contains NaN it returns NaN.
source
Arblib.getinterval — Function
getinterval([T, ] x::ArbOrRef)
Returns a tuple (l, u) representing an interval [l, u] enclosing the ball x, both of them are of type Arf. If T is given convert to this type, supports Arf, BigFloat and Arb.
If x contains NaN both l and u will be NaN.
See also getball.
source
Arblib.getball — Function
getball([T, ] x::ArbOrRef)
Returns a tuple (m::Arf, r::Mag) where m is the midpoint of the ball and r is the radius. If T is given convert both m and r to this type, supports Arf and Arb.
See also setball and getinterval.
source
Union and intersection
The methods Arblib.union and Arblib.intersection compute the union and intersection of balls. Note that these methods are not exported and different from Base.union and Base.intersect.
Arblib.union — Function
union(x::ArbOrRef, y::ArbOrRef)
 union(x::AcbOrRef, y::AcbOrRef)
 union(x::T, y::T) where {T<:Union{ArbPoly,AcbPoly,ArbSeries,AcbSeries}}
-union(x, y, z...)
Returns a ball containing the union of x and y. For polynomials and series the union is taken coefficient-wise.
union(x, y, z...) returns a ball containing the union of all given balls.
source
Arblib.intersection — Function
intersection(x::ArbOrRef, y::ArbOrRef)
+union(x, y, z...)
Returns a ball containing the union of x and y. For polynomials and series the union is taken coefficient-wise.
union(x, y, z...) returns a ball containing the union of all given balls.
source
Arblib.intersection — Function
intersection(x::ArbOrRef, y::ArbOrRef)
 intersection(x::T, y::T) where {T<:Union{ArbPoly,ArbSeries}}
-intersection(x, y, z...)
intersection(x, y) returns a ball containing the intersection of x and y. If x and y do not overlap (as given by overlaps(a, b)) throws an ArgumentError. For polynomials and series the intersection is taken coefficient-wise.
intersection(x, y, z...) returns a ball containing the intersection of all given balls. If all the balls do not overlap throws an ArgumentError.
source

+intersection(x, y, z...)

intersection(x, y) returns a ball containing the intersection of x and y. If x and y do not overlap (as given by overlaps(a, b)) throws an ArgumentError. For polynomials and series the intersection is taken coefficient-wise.

intersection(x, y, z...) returns a ball containing the intersection of all given balls. If all the balls do not overlap throws an ArgumentError.

source
diff --git a/dev/interface-integration/index.html b/dev/interface-integration/index.html index fdb2e94..e88218d 100644 --- a/dev/interface-integration/index.html +++ b/dev/interface-integration/index.html @@ -23,7 +23,7 @@ end; julia> Arblib.integrate(f, Acb(1, -5), Acb(1, 10), check_analytic = true, prec = 64) -[-9.0064084416559764 +/- 7.40e-17] + [23.8636067095598007 +/- 9.03e-17]imsource
Arblib.integrate! — Function
integrate!(f!, res::Acb, a::Number, b::Number;
+[-9.0064084416559764 +/- 7.40e-17] + [23.8636067095598007 +/- 9.03e-17]im
source
Arblib.integrate! — Function
integrate!(f!, res::Acb, a::Number, b::Number;
     check_analytic::Bool = false,
     take_prec::Bool = false,
     prec::Integer = precision(res),
@@ -42,4 +42,4 @@
 julia> f! = (res, z; analytic = false) -> Arblib.sqrt_analytic!(res, z, analytic);
 
 julia> Arblib.integrate!(f!, Acb(0), Acb(1, -5), Acb(1, 10), check_analytic = true, prec = 64)
-[-9.0064084416559764 +/- 6.53e-17] + [23.8636067095598007 +/- 6.98e-17]im
source
+[-9.0064084416559764 +/- 6.53e-17] + [23.8636067095598007 +/- 6.98e-17]imsource diff --git a/dev/interface-mutable/index.html b/dev/interface-mutable/index.html index 4068753..13b204e 100644 --- a/dev/interface-mutable/index.html +++ b/dev/interface-mutable/index.html @@ -1,5 +1,5 @@ -Mutable arithmetic · Arblib.jl
GitHub

Mutable arithmetic

The high level interface can be combined with the low level wrapper to allow for efficient computations using mutable arithmetic.

In the future it would be nice to have an interface to MutableArithmetics.jl, see #118.

The following methods are useful for mutating part of a value

Arblib.radref — Function
radref(x::ArbLike, prec = precision(x))

Return a MagRef referencing the radius of x.

source
Arblib.midref — Function
midref(x::ArbLike, prec = precision(x))

Return an ArfRef referencing the midpoint of x.

source
Arblib.realref — Function
realref(z::AcbLike, prec = precision(z))

Return an ArbRef referencing the real part of x.

source
Arblib.imagref — Function
imagref(z::AcbLike, prec = precision(z))

Return an ArbRef referencing the imaginary part of x.

source
Arblib.ref — Function
ref(v::Union{ArbVectorOrRef,AcbVectorOrRef}, i)

Similar to v[i] but instead of an Arb or Acb returns an ArbRef or AcbRef which still shares the memory with the i-th entry of v.

source
ref(A::Union{ArbMatrixOrRef,AcbMatrixOrRef}, i, j)

Similar to A[i,j] but instead of an Arb or Acb returns an ArbRef or AcbRef which still shares the memory with the (i,j)-th entry of A.

source
ref(p::Union{ArbPoly,ArbSeries,AcbPoly,AcbSeries}, i)

Similar to p[i] but instead of an Arb or Acb returns an ArbRef or AcbRef which shares the memory with the i-th coefficient of p.

Note

Using ref for reading coefficients is always safe, but if the coefficient is mutated then care has to be taken. See the comment further down for how to handle mutation.

It only allows accessing coefficients that are allocated. For ArbPoly and AcbPoly this is typically all coefficients up to the degree of the polynomial, but can be higher if for example Arblib.fit_length! is used. For ArbSeries and AcbSeries all coefficients up to the degree of the series are guaranteed to be allocated, even if the underlying polynomial has a lower degree.

If the coefficient is mutated in a way that the degree of the polynomial changes then one needs to also update the internally stored length of the polynomial.

  • If the new degree is the same or lower this can be achieved with
    Arblib.normalise!(p)
  • If the new degree is higher you need to manually set the length. This can be achieved with
    Arblib.set_length!(p, len)
+Mutable arithmetic · Arblib.jl
    GitHub
    Mutable arithmetic
    The high level interface can be combined with the low level wrapper to allow for efficient computations using mutable arithmetic.
    In the future it would be nice to have an interface to MutableArithmetics.jl, see #118.
    The following methods are useful for mutating part of a value
    Arblib.radref — Function
    radref(x::ArbLike, prec = precision(x))
    Return a MagRef referencing the radius of x.
    source
    Arblib.midref — Function
    midref(x::ArbLike, prec = precision(x))
    Return an ArfRef referencing the midpoint of x.
    source
    Arblib.realref — Function
    realref(z::AcbLike, prec = precision(z))
    Return an ArbRef referencing the real part of x.
    source
    Arblib.imagref — Function
    imagref(z::AcbLike, prec = precision(z))
    Return an ArbRef referencing the imaginary part of x.
    source
    Arblib.ref — Function
    ref(v::Union{ArbVectorOrRef,AcbVectorOrRef}, i)
    Similar to v[i] but instead of an Arb or Acb returns an ArbRef or AcbRef which still shares the memory with the i-th entry of v.
    source
    ref(A::Union{ArbMatrixOrRef,AcbMatrixOrRef}, i, j)
    Similar to A[i,j] but instead of an Arb or Acb returns an ArbRef or AcbRef which still shares the memory with the (i,j)-th entry of A.
    source
    ref(p::Union{ArbPoly,ArbSeries,AcbPoly,AcbSeries}, i)
    Similar to p[i] but instead of an Arb or Acb returns an ArbRef or AcbRef which shares the memory with the i-th coefficient of p.
    Note
    Using ref for reading coefficients is always safe, but if the coefficient is mutated then care has to be taken. See the comment further down for how to handle mutation.
    It only allows accessing coefficients that are allocated. For ArbPoly and AcbPoly this is typically all coefficients up to the degree of the polynomial, but can be higher if for example Arblib.fit_length! is used. For ArbSeries and AcbSeries all coefficients up to the degree of the series are guaranteed to be allocated, even if the underlying polynomial has a lower degree.
    If the coefficient is mutated in a way that the degree of the polynomial changes then one needs to also update the internally stored length of the polynomial.
    • If the new degree is the same or lower this can be achieved with
      Arblib.normalise!(p)
    • If the new degree is higher you need to manually set the length. This can be achieved with
      Arblib.set_length!(p, len)
 Arblib.normalise!(p)
      where len is one higher than (an upper bound of) the new degree.
    See the extended help for more details.
    Extended help
    Here is an example were the leading coefficient is mutated so that the degree is lowered.
    julia> p = ArbPoly([1, 2], prec = 64) # Polynomial of degree 1
 1.0 + 2.0⋅x
 
@@ -35,27 +35,27 @@
 1
 
 julia> Arblib.set_length!(q, 3) # After explicitly setting the length to 3 it is ok
-1.0 + 2.0⋅x + 1.0⋅x^2 + 𝒪(x^3)
    source
    Examples
    Compare computing $\sqrt{x^2 + y^2}$ using mutable arithmetic with the default.
    julia> using Arblib, BenchmarkTools
    julia> x = Arb(1 // 3)[0.33333333333333333333333333333333333333333333333333333333333333333333333333333 +/- 4.78e-78]
    julia> y = Arb(1 // 5)[0.20000000000000000000000000000000000000000000000000000000000000000000000000000 +/- 3.89e-78]
    julia> res = zero(x)0
    julia> f(x, y) = sqrt(x^2 + y^2)f (generic function with 1 method)
    julia> f!(res, x, y) = begin
+1.0 + 2.0⋅x + 1.0⋅x^2 + 𝒪(x^3)
    source

Examples

Compare computing $\sqrt{x^2 + y^2}$ using mutable arithmetic with the default.

julia> using Arblib, BenchmarkTools
julia> x = Arb(1 // 3)[0.33333333333333333333333333333333333333333333333333333333333333333333333333333 +/- 4.78e-78]
julia> y = Arb(1 // 5)[0.20000000000000000000000000000000000000000000000000000000000000000000000000000 +/- 3.89e-78]
julia> res = zero(x)0
julia> f(x, y) = sqrt(x^2 + y^2)f (generic function with 1 method)
julia> f!(res, x, y) = begin
            Arblib.sqr!(res, x)
            Arblib.fma!(res, res, y, y)
            return Arblib.sqrt!(res, res)
        endf! (generic function with 1 method)
julia> @benchmark f($x, $y) samples=10000 evals=500BenchmarkTools.Trial: 10000 samples with 500 evaluations.
- Range (min … max):  529.112 ns … 237.753 μs  ┊ GC (min … max):  0.00% … 78.83%
- Time  (median):     558.648 ns               ┊ GC (median):     0.00%
- Time  (mean ± σ):   949.940 ns ±   5.886 μs  ┊ GC (mean ± σ):  14.82% ±  2.38%
+ Range (min … max):  549.320 ns … 249.312 μs  ┊ GC (min … max):  0.00% … 80.78%
+ Time  (median):     561.642 ns               ┊ GC (median):     0.00%
+ Time  (mean ± σ):   961.959 ns ±   5.989 μs  ┊ GC (mean ± σ):  15.45% ±  2.49%
 
-  ▁▁ ▆█▇▄▄▄▂▁            ▁                                      ▁
-  ██▇███████████▇▅▆▅▅▅▄▄▇██▅▆▇▇▇▅▅▄▃▄▄▄▄▄▅▂▃▄▄▂▄▂▃▂▄▄▅▄▄▅▅▅▅▄▅▅ █
-  529 ns        Histogram: log(frequency) by time        894 ns <
+  ▆█▇▃▄▄▁           ▁                                           ▂
+  ██████████▇▆▆▆▆▅▆▇██▇▇▇▇▆▅▄▅▄▅▅▁▃▄▄▅▄▃▄▅▃▅▅▅▆▆▆▇██▇▆▇▇▆▆▆▆▅▅▄ █
+  549 ns        Histogram: log(frequency) by time        959 ns <
 
  Memory estimate: 448 bytes, allocs estimate: 8.
julia> @benchmark f!($res, $x, $y) samples=10000 evals=500BenchmarkTools.Trial: 10000 samples with 500 evaluations.
- Range (min … max):  331.382 ns … 507.692 ns  ┊ GC (min … max): 0.00% … 0.00%
- Time  (median):     337.532 ns               ┊ GC (median):    0.00%
- Time  (mean ± σ):   338.747 ns ±   6.594 ns  ┊ GC (mean ± σ):  0.00% ± 0.00%
+ Range (min … max):  339.990 ns … 643.616 ns  ┊ GC (min … max): 0.00% … 0.00%
+ Time  (median):     344.180 ns               ┊ GC (median):    0.00%
+ Time  (mean ± σ):   346.250 ns ±  17.774 ns  ┊ GC (mean ± σ):  0.00% ± 0.00%
 
-           ▃▄▆▇▇█▇▆▄▄▄▄▄▂▁▂▁                      ▁▁▁           ▂
-  ▃▁▁▁▁▄▃▆▇█████████████████▅▅▆▅▁▄▃▁▁▁▁▁▁▁▃▁▁▁▅▆▇███████▇▇▇▆▇▆▆ █
-  331 ns        Histogram: log(frequency) by time        358 ns <
+    ▂▄▆▇███▇▅▅▄▂▁▁                ▁▁▁▁▁                         ▂
+  ▄███████████████▆▆▄▅▃▁▁▃▃▁▁▁▁▅▆██████▇▇██▇▇▆▇▇▅▅▅▅▃▄▃▃▄▃▁▃▄▃▄ █
+  340 ns        Histogram: log(frequency) by time        373 ns <
 
  Memory estimate: 0 bytes, allocs estimate: 0.

Set the radius of the real part of an Acb.

julia> using Arblib
julia> z = Acb(1, 2)1.0 + 2.0im
julia> Arblib.set!(Arblib.radref(Arblib.realref(z)), 1e-10)1.0e-10
julia> z[1.000000000 +/- 1.01e-10] + 2.0im

Compare a naive implementation of polynomial evaluation using mutable arithmetic with one not using using it.

julia> using Arblib, BenchmarkTools
julia> p = ArbPoly(1:10)1.0 + 2.0⋅x + 3.0⋅x^2 + 4.0⋅x^3 + 5.0⋅x^4 + 6.0⋅x^5 + 7.0⋅x^6 + 8.0⋅x^7 + 9.0⋅x^8 + 10.0⋅x^9
julia> x = Arb(1 // 3)[0.33333333333333333333333333333333333333333333333333333333333333333333333333333 +/- 4.78e-78]
julia> res = zero(x)0
julia> function eval(p, x)
            res = zero(x)
@@ -74,30 +74,30 @@
            end
            return res
        endeval! (generic function with 1 method)
julia> @benchmark eval($p, $x) samples = 10000 evals = 30BenchmarkTools.Trial: 10000 samples with 30 evaluations.
- Range (min … max):  2.501 μs …  4.312 ms  ┊ GC (min … max):  0.00% … 70.66%
- Time  (median):     2.588 μs              ┊ GC (median):     0.00%
- Time  (mean ± σ):   6.579 μs ± 84.942 μs  ┊ GC (mean ± σ):  25.71% ±  2.03%
+ Range (min … max):  2.474 μs …  4.484 ms  ┊ GC (min … max):  0.00% … 81.17%
+ Time  (median):     2.559 μs              ┊ GC (median):     0.00%
+ Time  (mean ± σ):   6.660 μs ± 88.469 μs  ┊ GC (mean ± σ):  27.31% ±  2.08%
 
-  ██▆▅▃▂▂▁           ▃▂                                      ▁
-  █████████▇▆▄▄▄▂▄▄▄████▆▅▅▅▄▄▄▄▄▄▇▇▆▅▅▆▂▄▄▅▅▅▅▆▅▄▄▅▅▂▄▄▄▆█▇ █
-  2.5 μs       Histogram: log(frequency) by time     6.11 μs <
+  ▆█▆▅▄▃▂▁▁                                                  ▂
+  ███████████▇▆▆▅▅▅▃▅▅▁▄▄▃▁▁▄▁▁▃▃▃▁▃▄▁▁▁▄▁▄▃▁▁▃▄▁▁▁▁▁▁▃▁▁▁▃▃ █
+  2.47 μs      Histogram: log(frequency) by time     5.42 μs <
 
  Memory estimate: 3.94 KiB, allocs estimate: 70.
julia> @benchmark eval!($res, $p, $x) samples = 10000 evals = 30BenchmarkTools.Trial: 10000 samples with 30 evaluations.
- Range (min … max):  996.900 ns … 796.948 μs  ┊ GC (min … max): 0.00% … 35.50%
- Time  (median):       1.017 μs               ┊ GC (median):    0.00%
- Time  (mean ± σ):     1.102 μs ±   7.959 μs  ┊ GC (mean ± σ):  2.57% ±  0.35%
+ Range (min … max):  996.833 ns … 827.592 μs  ┊ GC (min … max): 0.00% … 35.66%
+ Time  (median):       1.013 μs               ┊ GC (median):    0.00%
+ Time  (mean ± σ):     1.102 μs ±   8.266 μs  ┊ GC (mean ± σ):  2.68% ±  0.36%
 
-        ▃▅█▆▆▆▃▄                                                
-  ▂▂▂▃▄▇█████████▇▆▄▄▃▃▃▃▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▁▂▂ ▃
+       ▅█▆▃▂▂▁                                                  
+  ▂▂▃▅████████▇▅▅▄▄▃▃▃▃▂▂▂▂▂▂▂▂▂▂▂▁▂▂▂▂▁▂▂▂▂▂▂▂▂▂▂▂▂▂▁▂▂▁▂▂▂▂▂▂ ▃
   997 ns           Histogram: frequency by time         1.11 μs <
 
  Memory estimate: 160 bytes, allocs estimate: 3.
julia> @benchmark $p($x) samples = 10000 evals = 30 # Arb implementation for referenceBenchmarkTools.Trial: 10000 samples with 30 evaluations.
- Range (min … max):  754.767 ns … 797.527 μs  ┊ GC (min … max): 0.00% … 35.17%
- Time  (median):     764.767 ns               ┊ GC (median):    0.00%
- Time  (mean ± σ):   848.949 ns ±   7.968 μs  ┊ GC (mean ± σ):  3.30% ±  0.35%
+ Range (min … max):  749.700 ns … 836.914 μs  ┊ GC (min … max): 0.00% … 34.75%
+ Time  (median):     758.400 ns               ┊ GC (median):    0.00%
+ Time  (mean ± σ):   847.571 ns ±   8.362 μs  ┊ GC (mean ± σ):  3.43% ±  0.35%
 
-      ▂▇▆█▃▁▂                                                   
-  ▂▂▃▆████████▇█▆▆▄▄▄▃▃▃▃▃▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▁▂▂▂▂▂▂▂▁▁▁▁▁▂▁▂▁▂▂ ▃
-  755 ns           Histogram: frequency by time          824 ns <
+    ▁█▇▅▁                                                       
+  ▂▃██████▆▇▆▅▄▄▃▃▃▃▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▁▁▁▁▁▁▁▂▁▂▁▁▁▁▁▁▁▁▂▂▁▂▂▂▁▁▂ ▃
+  750 ns           Histogram: frequency by time          842 ns <
 
- Memory estimate: 160 bytes, allocs estimate: 3.
+ Memory estimate: 160 bytes, allocs estimate: 3. diff --git a/dev/interface-series/index.html b/dev/interface-series/index.html index 5e8483d..ada4b38 100644 --- a/dev/interface-series/index.html +++ b/dev/interface-series/index.html @@ -1,2 +1,2 @@ -Series · Arblib.jl
GitHub

Series

Taylor series arithmetic allows for the computation of truncated Taylor series of functions and is a form of higher order automatic differentiation. See e.g. TaylorSeries.jl and TaylorDiff.jl for implementations of Taylor series in Julia.

The Arb library has good support for computing with polynomials as Taylor expansions. The types ArbSeries and AcbSeries are intended to make this easy to use from Julia. They are given by an ArbPoly/AcbPoly together with the length of the expansion.

Example

julia> using Arblib
julia> x0 = Arb(1 // 3, prec = 64)[0.3333333333333333333 +/- 4.24e-20]
julia> x = ArbSeries((x0, 1), degree = 5)[0.3333333333333333333 +/- 4.24e-20] + 1.0⋅x + 𝒪(x^6)
julia> sin(x)[0.3271946967961522441 +/- 8.51e-20] + [0.944956946314737664 +/- 4.30e-19]⋅x + [-0.1635973483980761221 +/- 6.09e-20]⋅x^2 + [-0.1574928243857896107 +/- 4.28e-20]⋅x^3 + [0.01363311236650634351 +/- 6.74e-21]⋅x^4 + [0.00787464121928948054 +/- 5.28e-21]⋅x^5 + 𝒪(x^6)
julia> sin(x)^2 + cos(x)^2[1.00000000000000000 +/- 4.33e-19] + [+/- 3.94e-19]⋅x + [+/- 5.34e-19]⋅x^2 + [+/- 2.53e-19]⋅x^3 + [+/- 2.48e-19]⋅x^4 + [+/- 5.91e-20]⋅x^5 + 𝒪(x^6)
+Series · Arblib.jl
GitHub

Series

Taylor series arithmetic allows for the computation of truncated Taylor series of functions and is a form of higher order automatic differentiation. See e.g. TaylorSeries.jl and TaylorDiff.jl for implementations of Taylor series in Julia.

The Arb library has good support for computing with polynomials as Taylor expansions. The types ArbSeries and AcbSeries are intended to make this easy to use from Julia. They are given by an ArbPoly/AcbPoly together with the length of the expansion.

Example

julia> using Arblib
julia> x0 = Arb(1 // 3, prec = 64)[0.3333333333333333333 +/- 4.24e-20]
julia> x = ArbSeries((x0, 1), degree = 5)[0.3333333333333333333 +/- 4.24e-20] + 1.0⋅x + 𝒪(x^6)
julia> sin(x)[0.3271946967961522441 +/- 8.51e-20] + [0.944956946314737664 +/- 4.30e-19]⋅x + [-0.1635973483980761221 +/- 6.09e-20]⋅x^2 + [-0.1574928243857896107 +/- 4.28e-20]⋅x^3 + [0.01363311236650634351 +/- 6.74e-21]⋅x^4 + [0.00787464121928948054 +/- 5.28e-21]⋅x^5 + 𝒪(x^6)
julia> sin(x)^2 + cos(x)^2[1.00000000000000000 +/- 4.33e-19] + [+/- 3.94e-19]⋅x + [+/- 5.34e-19]⋅x^2 + [+/- 2.53e-19]⋅x^3 + [+/- 2.48e-19]⋅x^4 + [+/- 5.91e-20]⋅x^5 + 𝒪(x^6)
diff --git a/dev/interface-types/index.html b/dev/interface-types/index.html index aa95157..5d0de8c 100644 --- a/dev/interface-types/index.html +++ b/dev/interface-types/index.html @@ -1,16 +1,16 @@ -Types · Arblib.jl
GitHub

Types

The package defines a number of types for the high level interface.

Basic

These types directly map to corresponding Arb types.

Arblib.ArbVector — Type
ArbVector <: DenseVector{Arb}
+Types · Arblib.jl
GitHub
Types
The package defines a number of types for the high level interface.
Basic
These types directly map to corresponding Arb types.
Arblib.ArbVector — Type
ArbVector <: DenseVector{Arb}
 ArbVector(n::Integer; prec::Integer = DEFAULT_PRECISION[])
 ArbVector(v::ArbVectorLike; shallow::Bool = false, prec::Integer = precision(v))
-ArbVector(v::AbstractVector; prec::Integer = _precision(v))
The constructor with n::Integer returns a vector with n elements filled with zeros. The other two constructors returns a copy of the given vector. If shallow = true then the returned vector shares the underlying data with the input, mutating one of them mutates both.
See also ArbRefVector.
source
Arblib.AcbVector — Type
AcbVector <: DenseVector{Acb}
+ArbVector(v::AbstractVector; prec::Integer = _precision(v))
The constructor with n::Integer returns a vector with n elements filled with zeros. The other two constructors returns a copy of the given vector. If shallow = true then the returned vector shares the underlying data with the input, mutating one of them mutates both.
See also ArbRefVector.
source
Arblib.AcbVector — Type
AcbVector <: DenseVector{Acb}
 AcbVector(n::Integer; prec::Integer = DEFAULT_PRECISION[])
 AcbVector(v::AcbVectorLike; shallow::Bool = false, prec::Integer = precision(v))
-AcbVector(v::AbstractVector; prec::Integer = _precision(v))
The constructor with n::Integer returns a vector with n elements filled with zeros. The other two constructors returns a copy of the given vector. If shallow = true then the returned vector shares the underlying data with the input, mutating one of them mutates both.
See also AcbRefVector.
source
Arblib.ArbMatrix — Type
ArbMatrix <: DenseMatrix{Arb}
+AcbVector(v::AbstractVector; prec::Integer = _precision(v))
The constructor with n::Integer returns a vector with n elements filled with zeros. The other two constructors returns a copy of the given vector. If shallow = true then the returned vector shares the underlying data with the input, mutating one of them mutates both.
See also AcbRefVector.
source
Arblib.ArbMatrix — Type
ArbMatrix <: DenseMatrix{Arb}
 ArbMatrix(r::Integer, c::Integer; prec::Integer = DEFAULT_PRECISION[])
 ArbMatrix(A::ArbMatrixLike; shallow::Bool = false, prec::Integer = precision(v))
 ArbMatrix(A::AbstractMatrix; prec::Integer = _precision(v))
-ArbMatrix(v::AbstractVector; prec::Integer = _precision(v))
The constructor with r::Integer, c::Integer returns a r × c filled with zeros. The other three constructors returns a copy of the given matrix or vector. If shallow = true then the returned matrix shares the underlying data with the input, mutating one of them mutates both.
See also ArbRefMatrix.
source
Arblib.AcbMatrix — Type
AcbMatrix <: DenseMatrix{Acb}
+ArbMatrix(v::AbstractVector; prec::Integer = _precision(v))
The constructor with r::Integer, c::Integer returns a r × c filled with zeros. The other three constructors returns a copy of the given matrix or vector. If shallow = true then the returned matrix shares the underlying data with the input, mutating one of them mutates both.
See also ArbRefMatrix.
source
Arblib.AcbMatrix — Type
AcbMatrix <: DenseMatrix{Acb}
 AcbMatrix(r::Integer, c::Integer; prec::Integer = DEFAULT_PRECISION[])
 AcbMatrix(A::AcbMatrixLike; shallow::Bool = false, prec::Integer = precision(v))
 AcbMatrix(A::AbstractMatrix; prec::Integer = _precision(v))
-AcbMatrix(v::AbstractVector; prec::Integer = _precision(v))
The constructor with r::Integer, c::Integer returns a r × c filled with zeros. The other three constructors returns a copy of the given matrix or vector. If shallow = true then the returned matrix shares the underlying data with the input, mutating one of them mutates both.
See also AcbRefMatrix.
source
Series
The package defines two series types, which are wrapper for the polynomial types with a specified degree.
Ref
In addition to these there are a number of Ref types, which allow for non-allocating access in a number of cases.
Arblib.ArbRefVector — Type
ArbRefVector <: DenseMatrix{ArbRef}
Similar to ArbVector but indexing elements returns an ArbRef referencing the corresponding element instead of an Arb copy of the element. The constructors are the same as for ArbVector
source
Arblib.AcbRefVector — Type
AcbRefVector <: DenseMatrix{AcbRef}
Similar to AcbVector but indexing elements returns an AcbRef referencing the corresponding element instead of an Acb copy of the element. The constructors are the same as for AcbVector
source
Arblib.ArbRefMatrix — Type
ArbRefMatrix <: DenseMatrix{ArbRef}
Similar to ArbMatrix but indexing elements returns an ArbRef referencing the corresponding element instead of an Arb copy of the element. The constructors are the same as for ArbMatrix
source
Arblib.AcbRefMatrix — Type
AcbRefMatrix <: DenseMatrix{AcbRef}
Similar to AcbMatrix but indexing elements returns an AcbRef referencing the corresponding element instead of an Acb copy of the element. The constructors are the same as for `AcbMatrix
source
Correspondence between types
We have the following table for the correspondence with between the Low level wrapper types and the high level interface types.
ArbWrapperHigh levelRef
mag_tmag_structMagMagRef
arf_tarf_structArfArfRef
arb_tarb_structArbArbRef
acb_tacb_structAcbAcbRef
arb_t*arb_vec_structArbVectorArbRefVector
acb_t*acb_vec_structAcbVectorAcbRefVector
arb_poly_tarb_poly_structArbPoly or ArbSeries
acb_poly_tacb_poly_structAcbPoly or AcbSeries
arb_mat_tarb_mat_structArbMatrixArbRefMatrix
acb_mat_tacb_mat_structAcbMatrixAcbRefMatrix

+AcbMatrix(v::AbstractVector; prec::Integer = _precision(v))

The constructor with r::Integer, c::Integer returns a r × c filled with zeros. The other three constructors returns a copy of the given matrix or vector. If shallow = true then the returned matrix shares the underlying data with the input, mutating one of them mutates both.

See also AcbRefMatrix.

source

Series

The package defines two series types, which are wrapper for the polynomial types with a specified degree.

Ref

In addition to these there are a number of Ref types, which allow for non-allocating access in a number of cases.

Arblib.ArbRefVector — Type
ArbRefVector <: DenseMatrix{ArbRef}

Similar to ArbVector but indexing elements returns an ArbRef referencing the corresponding element instead of an Arb copy of the element. The constructors are the same as for ArbVector

source
Arblib.AcbRefVector — Type
AcbRefVector <: DenseMatrix{AcbRef}

Similar to AcbVector but indexing elements returns an AcbRef referencing the corresponding element instead of an Acb copy of the element. The constructors are the same as for AcbVector

source
Arblib.ArbRefMatrix — Type
ArbRefMatrix <: DenseMatrix{ArbRef}

Similar to ArbMatrix but indexing elements returns an ArbRef referencing the corresponding element instead of an Arb copy of the element. The constructors are the same as for ArbMatrix

source
Arblib.AcbRefMatrix — Type
AcbRefMatrix <: DenseMatrix{AcbRef}

Similar to AcbMatrix but indexing elements returns an AcbRef referencing the corresponding element instead of an Acb copy of the element. The constructors are the same as for `AcbMatrix

source

Correspondence between types

We have the following table for the correspondence with between the Low level wrapper types and the high level interface types.

ArbWrapperHigh levelRef
mag_tmag_structMagMagRef
arf_tarf_structArfArfRef
arb_tarb_structArbArbRef
acb_tacb_structAcbAcbRef
arb_t*arb_vec_structArbVectorArbRefVector
acb_t*acb_vec_structAcbVectorAcbRefVector
arb_poly_tarb_poly_structArbPoly or ArbSeries
acb_poly_tacb_poly_structAcbPoly or AcbSeries
arb_mat_tarb_mat_structArbMatrixArbRefMatrix
acb_mat_tacb_mat_structAcbMatrixAcbRefMatrix
diff --git a/dev/rigorous/index.html b/dev/rigorous/index.html index a1b8e0b..ea9cee6 100644 --- a/dev/rigorous/index.html +++ b/dev/rigorous/index.html @@ -1,4 +1,4 @@ Rigorous numerics · Arblib.jl
GitHub

Rigorous numerics

Arb is made for rigorous numerics and any functions which do not produce rigorous results are clearly marked as such. This is not the case with Julia in general and you therefore have to be careful when interacting with the ecosystem if you want your results to be completely rigorous. Below we discuss some things to be extra careful with.

Implicit promotion

Julia automatically promotes types in many cases and in particular you have to watch out for temporary non-rigorous values. For example 2(π * Arb(1 // 3)) is okay, but not 2π * Arb(1 // 3)

x = 2(π * Arb(1 // 3))
 y = 2π * Arb(1 // 3)
-Arblib.overlaps(x, y)

Non-rigorous algorithms

Standard numerical algorithms typically return (hopefully good) approximations. These algorithms can then not directly be used in rigorous numerical computations unless the error can be bounded.

For example Julias built in methods for solving linear systems doesn't produce rigorous results. Instead you would have to use the solves provided by Arb, such as Arblib.solve!.

Other examples would include integration and solving of differential equations.

Implementation details

In some cases the implementation in Julia implicitly makes certain assumptions to improve performance and this can lead to issues.

For example, prior to Julia version 1.8 the minimum and maximum methods in Julia checked for NaN results (on which is short fuses) using x == x, which works for most numerical types but not for Arb (x == x is only true if the radius is zero). See https://github.com/JuliaLang/julia/issues/36287 and in particular https://github.com/JuliaLang/julia/issues/45932 for more details. Since Julia version 1.8 the minimum and maximum methods work correctly for Arb, for earlier versions of Julia it only works correctly in some cases.

These types of problems are the hardest to find since they are not clear from the documentation but you have to read the implementation, @which and @less are your friends in these cases.

+Arblib.overlaps(x, y)

Non-rigorous algorithms

Standard numerical algorithms typically return (hopefully good) approximations. These algorithms can then not directly be used in rigorous numerical computations unless the error can be bounded.

For example Julias built in methods for solving linear systems doesn't produce rigorous results. Instead you would have to use the solves provided by Arb, such as Arblib.solve!.

Other examples would include integration and solving of differential equations.

Implementation details

In some cases the implementation in Julia implicitly makes certain assumptions to improve performance and this can lead to issues.

For example, prior to Julia version 1.8 the minimum and maximum methods in Julia checked for NaN results (on which is short fuses) using x == x, which works for most numerical types but not for Arb (x == x is only true if the radius is zero). See https://github.com/JuliaLang/julia/issues/36287 and in particular https://github.com/JuliaLang/julia/issues/45932 for more details. Since Julia version 1.8 the minimum and maximum methods work correctly for Arb, for earlier versions of Julia it only works correctly in some cases.

These types of problems are the hardest to find since they are not clear from the documentation but you have to read the implementation, @which and @less are your friends in these cases.

diff --git a/dev/wrapper-fpwrap/index.html b/dev/wrapper-fpwrap/index.html index 63f0b5f..0c8eb95 100644 --- a/dev/wrapper-fpwrap/index.html +++ b/dev/wrapper-fpwrap/index.html @@ -3,5 +3,5 @@ x::Union{Float16, Float32, Float64}; error_on_failure::Bool = Arblib.ArbCall.fpwrap_error_on_failure_default(), correct_rounding::Bool = false, work_limit::Integer = 8, -)source
Arblib.ArbCall.ArbFPWrapFunction — Type
ArbFPWrapFunction{T}(fname, args)
-ArbFPWrapFunction(str)

Struct representing an Arb function from the arb_fpwrap.h module.

source
Arblib.ArbCall.jlcode — Method
jlcode(af::ArbFPWrapFunction, jl_fname = jlfname(af))

Generate the Julia code for calling a function from the fpwrap module of Arb from Julia.

source

The name for the generated method is given by removing the arb prefix and the double or cdouble in the middle of the name.

The flag argument that the C functions take are split into several keyword arguments in Julia. For the double type this is correct_rounding::Bool = false and work_limit::Integer = 8. For the cdouble type it also includes accurate_parts::Bool = false. The default values correspond to setting the flag to 0 in C.

The C functions return an int flag indicating the status. If the return flag is FPWRAP_SUCCESS the computed value is returned. If the return flag is FPWRAP_UNABLE it throws an error if the keyword argument error_on_failure is true and returns NaN otherwise. The default value for error_on_failure is handled by the following two methods

Arblib.ArbCall.fpwrap_error_on_failure_default — Function
fpwrap_error_on_failure_default()

Function giving the default value for the argument error_on_failure. See also fpwrap_error_on_failure_default_set.

source
Arblib.ArbCall.fpwrap_error_on_failure_default_set — Function
fpwrap_error_on_failure_default_set(value::Bool)

Set the default value for the argument error_on_failure for fpwrap methods. See also fpwrap_error_on_failure_default.

source
+)source
Arblib.ArbCall.ArbFPWrapFunction — Type
ArbFPWrapFunction{T}(fname, args)
+ArbFPWrapFunction(str)

Struct representing an Arb function from the arb_fpwrap.h module.

source
Arblib.ArbCall.jlcode — Method
jlcode(af::ArbFPWrapFunction, jl_fname = jlfname(af))

Generate the Julia code for calling a function from the fpwrap module of Arb from Julia.

source

The name for the generated method is given by removing the arb prefix and the double or cdouble in the middle of the name.

The flag argument that the C functions take are split into several keyword arguments in Julia. For the double type this is correct_rounding::Bool = false and work_limit::Integer = 8. For the cdouble type it also includes accurate_parts::Bool = false. The default values correspond to setting the flag to 0 in C.

The C functions return an int flag indicating the status. If the return flag is FPWRAP_SUCCESS the computed value is returned. If the return flag is FPWRAP_UNABLE it throws an error if the keyword argument error_on_failure is true and returns NaN otherwise. The default value for error_on_failure is handled by the following two methods

Arblib.ArbCall.fpwrap_error_on_failure_default — Function
fpwrap_error_on_failure_default()

Function giving the default value for the argument error_on_failure. See also fpwrap_error_on_failure_default_set.

source
Arblib.ArbCall.fpwrap_error_on_failure_default_set — Function
fpwrap_error_on_failure_default_set(value::Bool)

Set the default value for the argument error_on_failure for fpwrap methods. See also fpwrap_error_on_failure_default.

source
diff --git a/dev/wrapper-methods/index.html b/dev/wrapper-methods/index.html index 4a40ed3..957d16c 100644 --- a/dev/wrapper-methods/index.html +++ b/dev/wrapper-methods/index.html @@ -1,4 +1,4 @@ -Methods · Arblib.jl
GitHub

Methods

The methods for the low level wrapper are automatically generated by parsing the Arb documentation. This is handled by the Arblib.ArbCall module.

Parsing

The parsing is handled by

Arblib.ArbCall.parse_and_generate_arbdoc — Function
parse_and_generate_arbdoc(doc_dir, out_dir = "src/arbcalls/"; filenames, verbose)

Parses the Flint documentation and generates corresponding Julia files. The value of doc_dir should be a path to the directory doc/source/ in the Flint directory.

The filenames argument can be given to specify specific doc files to use. The verbose argument can be set to true to give more information about the result of the parsing.

source

Note that the parsing is done ahead of time and the generated files in src/arbcalls/ are added to git. As a user of the package you therefore typically don't need to care about this step.

Generated methods

The automatic generation of the methods is handled by

Arblib.ArbCall.jlcode — Method
jlcode(af::ArbFunction, jl_fname = jlfname(af))

Generate the Julia code for calling the Arb function from Julia.

source

The main things to understand is how the name of the generated function is determined, how the arguments are handled and the return value.

Naming

The name of the Arb function is "Juliafied" using the following guidelines:

  1. Prefixes and suffixes a function name which only refer to the type of input are removed since Julia has multiple dispatch to deal with this problem.
  2. Functions which modify the first argument get an ! appended to the name.

The implementation is based on heuristics for determining when part of the function name is referring to the type or when the function modifies the argument. This works well for the majority of functions but gives a few odd cases.

Arguments

The arguments of the function are represented by

Arblib.ArbCall.Carg — Type
Carg{T}(name, isconst)
+Methods · Arblib.jl
GitHub
Methods
The methods for the low level wrapper are automatically generated by parsing the Arb documentation. This is handled by the Arblib.ArbCall module.
Parsing
The parsing is handled by
Arblib.ArbCall.parse_and_generate_arbdoc — Function
parse_and_generate_arbdoc(doc_dir, out_dir = "src/arbcalls/"; filenames, verbose)
Parses the Flint documentation and generates corresponding Julia files. The value of doc_dir should be a path to the directory doc/source/ in the Flint directory.
The filenames argument can be given to specify specific doc files to use. The verbose argument can be set to true to give more information about the result of the parsing.
source
Note that the parsing is done ahead of time and the generated files in src/arbcalls/ are added to git. As a user of the package you therefore typically don't need to care about this step.
Generated methods
The automatic generation of the methods is handled by
Arblib.ArbCall.jlcode — Method
jlcode(af::ArbFunction, jl_fname = jlfname(af))
Generate the Julia code for calling the Arb function from Julia.
source
The main things to understand is how the name of the generated function is determined, how the arguments are handled and the return value.
Naming
The name of the Arb function is "Juliafied" using the following guidelines:
  1. Prefixes and suffixes a function name which only refer to the type of input are removed since Julia has multiple dispatch to deal with this problem.
  2. Functions which modify the first argument get an ! appended to the name.
The implementation is based on heuristics for determining when part of the function name is referring to the type or when the function modifies the argument. This works well for the majority of functions but gives a few odd cases.
Arguments
The arguments of the function are represented by
Arblib.ArbCall.Carg — Type
Carg{T}(name, isconst)
 Carg(str::AbstractString)
Struct representing a argument to a C function in the Arb library. The corresponding Julia type is T, name is the name of the argument, isconst is true if the argument is declared as a const.
julia> Arblib.ArbCall.Carg("const arb_t x")
-Arblib.ArbCall.Carg{Arb}(:x, true)
source
For the generated method the allowed types for the argument is determined by
Arblib.ArbCall.jltype — Function
jltype(ca::Carg{T})
The most general Julia type for which we allow automatic conversion to the Arblib.ArbCall.ctype of ca.
These conversations should be done without any loss of information, for example for floating point numbers we only allow conversion from types with lower precision. In general the conversion is done using Base.cconvert.
source
Some arguments are automatically converted to keyword arguments.
  1. For functions which take a precision argument this argument becomes a prec::Integer keyword argument which is by default set to the precision of the first argument (if applicable).
  2. For functions which take a rounding mode argument this argument becomes a rnd::Union{Arblib.arb_rnd,RoundingMode} keyword argument which is by default set to RoundNearest.
  3. For functions which takes a flag argument this argument becomes a flag::Integer keyword argument which is by default set to 0.
  4. For functions which takes an argument giving the length of the vector preceding the argument this argument becomes a keyword argument which is by default set to the length of the preceding vector. In this case the name of the keyword argument is the same as the argument name in the function declaration.
As with the naming the implementation is based on heuristics for determining when an argument is supposed to be a certain kind of keyword argument.
Return value
The returned value is determined in the following way
  1. For functions which have the C function has return type void and modify the first argument the generated method returns the first argument. This is follows the normal convention in Julia.
  2. For predicates, for which the C function returns int, the return value is converted to a Bool.
  3. Otherwise the return type is the same as for the C function.
Examples
For example Arb declares the following functions
  1. void arb_zero(arb_t x)
  2. slong arb_rel_error_bits(const arb_t x)
  3. int arb_is_zero(const arb_t x)
  4. void arb_add(arb_t z, const arb_t x, const arb_t y, slong prec)
  5. void arb_add_arf(arb_t z, const arb_t x, const arf_t y, slong prec)
  6. void arb_add_ui(arb_t z, const arb_t x, ulong y, slong prec)
  7. void arb_add_si(arb_t z, const arb_t x, slong y, slong prec)
  8. void arb_sin(arb_t s, const arb_t x, slong prec)
  9. void arb_cos(arb_t c, const arb_t x, slong prec)
  10. void arb_sin_cos(arb_t s, arb_t c, const arb_t x, slong prec)
  11. int arf_add(arf_t res, const arf_t x, const arf_t y, slong prec, arf_rnd_t rnd)
For which the following methods are generated
  1. zero!(x::ArbLike)::ArbLike
  2. rel_error_bits(x::ArbLike)::Int
  3. is_zero(x::ArbLike)::Bool
  4. add!(z::ArbLike, x::ArbLike, y::ArbLike; prec::Integer = _precision(z))::ArbLike
  5. add!(z::ArbLike, x::ArbLike, y::ArfLike; prec::Integer = _precision(z))::ArbLike
  6. add!(z::ArbLike, x::ArbLike, y::Unsigned; prec::Integer = _precision(z))::ArbLike
  7. add!(z::ArbLike, x::ArbLike, y::Integer; prec::Integer = _precision(z))::ArbLike
  8. sin!(s::ArbLike, x::ArbLike; prec::Integer = _precision(s))::ArbLike
  9. cos!(c::ArbLike, x::ArbLike; prec::Integer = _precision(c))::ArbLike
  10. sin_cos!(s::ArbLike, c::ArbLike, x::ArbLike, prec::Integer = _precision(s))::ArbLike
  11. add!(res::ArfLike, x::ArfLike, y::ArfLike; prec::Integer = _precision(res), rnd::Union{Arblib.arb_rnd, RoundingMode} = RoundNearest)::Int32

+Arblib.ArbCall.Carg{Arb}(:x, true)
source

For the generated method the allowed types for the argument is determined by

Arblib.ArbCall.jltype — Function
jltype(ca::Carg{T})

The most general Julia type for which we allow automatic conversion to the Arblib.ArbCall.ctype of ca.

These conversations should be done without any loss of information, for example for floating point numbers we only allow conversion from types with lower precision. In general the conversion is done using Base.cconvert.

source

Some arguments are automatically converted to keyword arguments.

  1. For functions which take a precision argument this argument becomes a prec::Integer keyword argument which is by default set to the precision of the first argument (if applicable).
  2. For functions which take a rounding mode argument this argument becomes a rnd::Union{Arblib.arb_rnd,RoundingMode} keyword argument which is by default set to RoundNearest.
  3. For functions which takes a flag argument this argument becomes a flag::Integer keyword argument which is by default set to 0.
  4. For functions which takes an argument giving the length of the vector preceding the argument this argument becomes a keyword argument which is by default set to the length of the preceding vector. In this case the name of the keyword argument is the same as the argument name in the function declaration.

As with the naming the implementation is based on heuristics for determining when an argument is supposed to be a certain kind of keyword argument.

Return value

The returned value is determined in the following way

  1. For functions which have the C function has return type void and modify the first argument the generated method returns the first argument. This is follows the normal convention in Julia.
  2. For predicates, for which the C function returns int, the return value is converted to a Bool.
  3. Otherwise the return type is the same as for the C function.

Examples

For example Arb declares the following functions

  1. void arb_zero(arb_t x)
  2. slong arb_rel_error_bits(const arb_t x)
  3. int arb_is_zero(const arb_t x)
  4. void arb_add(arb_t z, const arb_t x, const arb_t y, slong prec)
  5. void arb_add_arf(arb_t z, const arb_t x, const arf_t y, slong prec)
  6. void arb_add_ui(arb_t z, const arb_t x, ulong y, slong prec)
  7. void arb_add_si(arb_t z, const arb_t x, slong y, slong prec)
  8. void arb_sin(arb_t s, const arb_t x, slong prec)
  9. void arb_cos(arb_t c, const arb_t x, slong prec)
  10. void arb_sin_cos(arb_t s, arb_t c, const arb_t x, slong prec)
  11. int arf_add(arf_t res, const arf_t x, const arf_t y, slong prec, arf_rnd_t rnd)

For which the following methods are generated

  1. zero!(x::ArbLike)::ArbLike
  2. rel_error_bits(x::ArbLike)::Int
  3. is_zero(x::ArbLike)::Bool
  4. add!(z::ArbLike, x::ArbLike, y::ArbLike; prec::Integer = _precision(z))::ArbLike
  5. add!(z::ArbLike, x::ArbLike, y::ArfLike; prec::Integer = _precision(z))::ArbLike
  6. add!(z::ArbLike, x::ArbLike, y::Unsigned; prec::Integer = _precision(z))::ArbLike
  7. add!(z::ArbLike, x::ArbLike, y::Integer; prec::Integer = _precision(z))::ArbLike
  8. sin!(s::ArbLike, x::ArbLike; prec::Integer = _precision(s))::ArbLike
  9. cos!(c::ArbLike, x::ArbLike; prec::Integer = _precision(c))::ArbLike
  10. sin_cos!(s::ArbLike, c::ArbLike, x::ArbLike, prec::Integer = _precision(s))::ArbLike
  11. add!(res::ArfLike, x::ArfLike, y::ArfLike; prec::Integer = _precision(res), rnd::Union{Arblib.arb_rnd, RoundingMode} = RoundNearest)::Int32
diff --git a/dev/wrapper-types/index.html b/dev/wrapper-types/index.html index 86a4e70..e003252 100644 --- a/dev/wrapper-types/index.html +++ b/dev/wrapper-types/index.html @@ -1,5 +1,5 @@ -Types · Arblib.jl
GitHub

Types

The package defines the following types which map directly to Arb types with the corresponding name. In most cases you should not use these types directly but use the types from the High level interface.

For each low-level type there is a union of types that can be interpreted as the low-level type. These are the types that can be given directly as arguments to the low-level methods. Below you find these union-types.

Note that the show method is overloaded for these union types, this is to make method declarations easier to read in the REPL. As an example we can print the methods for Arblib.sin! and we see that it prints ArbLike instead of the much longer Union{Ptr{Arblib.arb_struct}, Arb, ArbRef, Arblib.arb_struct}.

julia> using Arblib
julia> methods(Arblib.sin!)# 4 methods for generic function "sin!" from Arblib:
+Types · Arblib.jl
GitHub
Types
The package defines the following types which map directly to Arb types with the corresponding name. In most cases you should not use these types directly but use the types from the High level interface.
For each low-level type there is a union of types that can be interpreted as the low-level type. These are the types that can be given directly as arguments to the low-level methods. Below you find these union-types.
Note that the show method is overloaded for these union types, this is to make method declarations easier to read in the REPL. As an example we can print the methods for Arblib.sin! and we see that it prints ArbLike instead of the much longer Union{Ptr{Arblib.arb_struct}, Arb, ArbRef, Arblib.arb_struct}.
julia> using Arblib
julia> methods(Arblib.sin!)# 4 methods for generic function "sin!" from Arblib:
  [1] sin!(s::AcbLike, z::AcbLike; prec)
      @ ~/work/Arblib.jl/Arblib.jl/src/ArbCall/ArbFunction.jl:176
  [2] sin!(s::AcbLike, z::AcbLike, prec::Integer)
@@ -7,4 +7,4 @@
  [3] sin!(s::ArbLike, x::ArbLike; prec)
      @ ~/work/Arblib.jl/Arblib.jl/src/ArbCall/ArbFunction.jl:176
  [4] sin!(s::ArbLike, x::ArbLike, prec::Integer)
-     @ ~/work/Arblib.jl/Arblib.jl/src/ArbCall/ArbFunction.jl:152

+     @ ~/work/Arblib.jl/Arblib.jl/src/ArbCall/ArbFunction.jl:152