Real balls

Real balls

Arbitrary precision real ball arithmetic is supplied by Arb which provides a ball representation which tracks error bounds rigorously. Real numbers are represented in mid-rad interval form $[m \pm r] = [m-r, m+r]$.

The Arb real field is constructed using the ArbField constructor. This constructs the parent object for the Arb real field.

However, we define

RealField = ArbField

so that one can construct the Arb real field parent object using RealField instead of ArbField.

The types of real balls in Nemo are given in the following table, along with the libraries that provide them and the associated types of the parent objects.

LibraryFieldElement typeParent type
Arb$\mathbb{R}$ (balls)arbArbField

All the real field types belong to the Field abstract type and the types of elements in this field, i.e. balls in this case, belong to the FieldElem abstract type.

Real ball functionality

Real balls in Nemo implement the full AbstractAlgebra.jl field interface.

https://nemocas.github.io/AbstractAlgebra.jl/fields.html

Below, we document the additional functionality provided for real balls.

Constructors

In order to construct real balls in Nemo, one must first construct the Arb real field itself. This is accomplished with the following constructor.

ArbField(prec::Int)

Return the Arb field with precision in bits prec used for operations on interval midpoints. The precision used for interval radii is a fixed implementation-defined constant (30 bits).

We define

RealField = ArbField

so that one can use RealField in place of ArbField.

Here is an example of creating an Arb real field and using the resulting parent object to coerce values into the resulting field.

Examples

RR = RealField(64)

a = RR("0.25")
b = RR("0.1")
c = RR(0.5)
d = RR(12)

Note that whilst one can coerce double precision floating point values into an Arb real field, unless those values can be represented exactly in double precision the resulting ball can't be any more precise than the double precision supplied.

If instead, values can be represented precisely using decimal arithmetic then one can supply them to Arb using a string. In this case, Arb will store them to the precision specified when creating the Arb field.

If the values can be stored precisely as a binary floating point number, Arb will store the values exactly. See the function isexact below for more information.

Real ball constructors

Nemo.ballMethod.
ball(mid::arb, rad::arb)

Constructs an arb enclosing the range $[m-|r|, m+|r|]$, given the pair $(m, r)$.

source

Examples

RR = RealField(64)

c = ball(RR(3), RR("0.0001"))

Conversions

Base.convertMethod.
convert(::Type{Float64}, x::arb)

Return the midpoint of $x$ rounded down to a machine double.

source

Basic manipulation

Nemo.isnonzeroMethod.
isnonzero(x::arb)

Return true if $x$ is certainly not equal to zero, otherwise return false.

source
Base.isfiniteMethod.
isfinite(x::arb)

Return true if $x$ is finite, i.e. having finite midpoint and radius, otherwise return false.

source
Nemo.isexactMethod.
isexact(x::arb)

Return true if $x$ is exact, i.e. has zero radius, otherwise return false.

source
Nemo.isintMethod.
isint(x::arb)

Return true if $x$ is an exact integer, otherwise return false.

source
Nemo.ispositiveMethod.
ispositive(x::arb)

Return true if $x$ is certainly positive, otherwise return false.

source
Nemo.isnonnegativeMethod.
isnonnegative(x::arb)

Return true if $x$ is certainly nonnegative, otherwise return false.

source
isnegative(x::arb)

Return true if $x$ is certainly negative, otherwise return false.

source
Nemo.isnonpositiveMethod.
isnonpositive(x::arb)

Return true if $x$ is certainly nonpositive, otherwise return false.

source
Nemo.midpointMethod.
midpoint(x::arb)

Return the midpoint of the ball $x$ as an Arb ball.

source
Nemo.radiusMethod.
radius(x::arb)

Return the radius of the ball $x$ as an Arb ball.

source
Nemo.accuracy_bitsMethod.
accuracy_bits(x::arb)

Return the relative accuracy of $x$ measured in bits, capped between typemax(Int) and -typemax(Int).

source

Examples

RR = RealField(64)

a = RR("1.2 +/- 0.001")
b = RR(3)

ispositive(a)
isfinite(b)
isint(b)
isnegative(a)
c = radius(a)
d = midpoint(b)
f = accuracy_bits(a)

Containment

It is often necessary to determine whether a given exact value or ball is contained in a given real ball or whether two balls overlap. The following functions are provided for this purpose.

Nemo.overlapsMethod.
overlaps(x::arb, y::arb)

Returns true if any part of the ball $x$ overlaps any part of the ball $y$, otherwise return false.

source
Base.containsMethod.
contains(x::arb, y::arb)

Returns true if the ball $x$ contains the ball $y$, otherwise return false.

source
Base.containsMethod.
contains(x::arb, y::Integer)

Returns true if the ball $x$ contains the given integer value, otherwise return false.

source
Base.containsMethod.
contains(x::arb, y::fmpz)

Returns true if the ball $x$ contains the given integer value, otherwise return false.

source
Base.containsMethod.
contains(x::arb, y::fmpq)

Returns true if the ball $x$ contains the given rational value, otherwise return false.

source
Base.containsMethod.
contains(x::arb, y::Rational{Integer})

Returns true if the ball $x$ contains the given rational value, otherwise return false.

source
Base.containsMethod.
contains(x::arb, y::BigFloat)

Returns true if the ball $x$ contains the given floating point value, otherwise return false.

source

The following functions are also provided for determining if a ball intersects a certain part of the real number line.

Nemo.contains_zeroMethod.
contains_zero(x::arb)

Returns true if the ball $x$ contains zero, otherwise return false.

source
contains_negative(x::arb)

Returns true if the ball $x$ contains any negative value, otherwise return false.

source
contains_positive(x::arb)

Returns true if the ball $x$ contains any positive value, otherwise return false.

source
contains_nonnegative(x::arb)

Returns true if the ball $x$ contains any nonnegative value, otherwise return false.

source
contains_nonpositive(x::arb)

Returns true if the ball $x$ contains any nonpositive value, otherwise return false.

source

Examples

RR = RealField(64)
x = RR("1 +/- 0.001")
y = RR("3")

overlaps(x, y)
contains(x, y)
contains(y, 3)
contains(x, ZZ(1)//2)
contains_zero(x)
contains_positive(y)

Comparison

Nemo provides a full range of comparison operations for Arb balls. Note that a ball is considered less than another ball if every value in the first ball is less than every value in the second ball, etc.

In addition to the standard comparison operators, we introduce an exact equality. This is distinct from arithmetic equality implemented by ==, which merely compares up to the minimum of the precisions of its operands.

Base.isequalMethod.
isequal(x::arb, y::arb)

Return true if the balls $x$ and $y$ are precisely equal, i.e. have the same midpoints and radii.

source

We also provide a full range of ad hoc comparison operators. These are implemented directly in Julia, but we document them as though isless and == were provided.

Function
==(x::arb, y::Integer)
==(x::Integer, y::arb)
==(x::arb, y::fmpz)
==(x::fmpz, y::arb)
==(x::arb, y::Float64)
==(x::Float64, y::arb)
isless(x::arb, y::Integer)
isless(x::Integer, y::arb)
isless(x::arb, y::fmpz)
isless(x::fmpz, y::arb)
isless(x::arb, y::Float64)
isless(x::Float64, y::arb)
isless(x::arb, y::BigFloat)
isless(x::BigFloat, y::arb)
isless(x::arb, y::fmpq)
isless(x::fmpq, y::arb)

Examples

RR = RealField(64)
x = RR("1 +/- 0.001")
y = RR("3")
z = RR("4")

isequal(x, deepcopy(x))
x == 3
ZZ(3) < z
x != 1.23

Absolute value

Base.absMethod.
abs(x::arb)

Return the absolute value of $x$.

source

Examples

RR = RealField(64)
x = RR("-1 +/- 0.001")

a = abs(x)

Shifting

Base.Math.ldexpMethod.
ldexp(x::arb, y::Int)

Return $2^yx$. Note that $y$ can be positive, zero or negative.

source
Base.Math.ldexpMethod.
ldexp(x::arb, y::fmpz)

Return $2^yx$. Note that $y$ can be positive, zero or negative.

source

Examples

RR = RealField(64)
x = RR("-3 +/- 0.001")

a = ldexp(x, 23)
b = ldexp(x, -ZZ(15))

Miscellaneous operations

Nemo.trimMethod.
trim(x::arb)

Return an arb interval containing $x$ but which may be more economical, by rounding off insignificant bits from the midpoint.

source
unique_integer(x::arb)

Return a pair where the first value is a boolean and the second is an fmpz integer. The boolean indicates whether the interval $x$ contains a unique integer. If this is the case, the second return value is set to this unique integer.

source
Nemo.setunionMethod.
setunion(x::arb, y::arb)

Return an arb containing the union of the intervals represented by $x$ and $y$.

source

Examples

RR = RealField(64)
x = RR("-3 +/- 0.001")
y = RR("2 +/- 0.5")

a = trim(x)
b, c = unique_integer(x)
d = setunion(x, y)

Constants

Nemo.const_piMethod.
const_pi(r::ArbField)

Return $\pi = 3.14159\ldots$ as an element of $r$.

source
Nemo.const_eMethod.
const_e(r::ArbField)

Return $e = 2.71828\ldots$ as an element of $r$.

source
Nemo.const_log2Method.
const_log2(r::ArbField)

Return $\log(2) = 0.69314\ldots$ as an element of $r$.

source
Nemo.const_log10Method.
const_log10(r::ArbField)

Return $\log(10) = 2.302585\ldots$ as an element of $r$.

source
Nemo.const_eulerMethod.
const_euler(r::ArbField)

Return Euler's constant $\gamma = 0.577215\ldots$ as an element of $r$.

source
Nemo.const_catalanMethod.
const_catalan(r::ArbField)

Return Catalan's constant $C = 0.915965\ldots$ as an element of $r$.

source
const_khinchin(r::ArbField)

Return Khinchin's constant $K = 2.685452\ldots$ as an element of $r$.

source
const_glaisher(r::ArbField)

Return Glaisher's constant $A = 1.282427\ldots$ as an element of $r$.

source

Examples

RR = RealField(200)

a = const_pi(RR)
b = const_e(RR)
c = const_euler(RR)
d = const_glaisher(RR)

Mathematical and special functions

Base.floorMethod.
floor(x::arb)

Compute the floor of $x$, i.e. the greatest integer not exceeding $x$, as an Arb.

source
Base.ceilMethod.
ceil(x::arb)

Return the ceiling of $x$, i.e. the least integer not less than $x$, as an Arb.

source
Base.sqrtMethod.
Base.sqrt(x::arb)

Return the square root of $x$.

source
Nemo.rsqrtMethod.
rsqrt(x::arb)

Return the reciprocal of the square root of $x$, i.e. $1/\sqrt{x}$.

source
Nemo.sqrt1pm1Method.
sqrt1pm1(x::arb)

Return $\sqrt{1+x}-1$, evaluated accurately for small $x$.

source
Base.logMethod.
log(x::arb)

Return the principal branch of the logarithm of $x$.

source
Base.log1pMethod.
log1p(x::arb)

Return $\log(1+x)$, evaluated accurately for small $x$.

source
Base.expMethod.
exp(x::arb)

Return the exponential of $x$.

source
Base.expm1Method.
expm1(x::arb)

Return $\exp(x)-1$, evaluated accurately for small $x$.

source
Base.sinMethod.
sin(x::arb)

Return the sine of $x$.

source
Base.cosMethod.
cos(x::arb)

Return the cosine of $x$.

source
Base.Math.sinpiMethod.
sinpi(x::arb)

Return the sine of $\pi x$.

source
Base.Math.cospiMethod.
cospi(x::arb)

Return the cosine of $\pi x$.

source
Base.tanMethod.
tan(x::arb)

Return the tangent of $x$.

source
Base.Math.cotMethod.
cot(x::arb)

Return the cotangent of $x$.

source
Nemo.tanpiMethod.
tanpi(x::arb)

Return the tangent of $\pi x$.

source
Nemo.cotpiMethod.
cotpi(x::arb)

Return the cotangent of $\pi x$.

source
Base.sinhMethod.
sinh(x::arb)

Return the hyperbolic sine of $x$.

source
Base.coshMethod.
cosh(x::arb)

Return the hyperbolic cosine of $x$.

source
Base.tanhMethod.
tanh(x::arb)

Return the hyperbolic tangent of $x$.

source
Base.Math.cothMethod.
coth(x::arb)

Return the hyperbolic cotangent of $x$.

source
Base.atanMethod.
atan(x::arb)

Return the arctangent of $x$.

source
Base.asinMethod.
asin(x::arb)

Return the arcsine of $x$.

source
Base.acosMethod.
acos(x::arb)

Return the arccosine of $x$.

source
Base.atanhMethod.
atanh(x::arb)

Return the hyperbolic arctangent of $x$.

source
Base.asinhMethod.
asinh(x::arb)

Return the hyperbolic arcsine of $x$.

source
Base.acoshMethod.
acosh(x::arb)

Return the hyperbolic arccosine of $x$.

source
Base.Math.gammaMethod.
gamma(x::arb)

Return the Gamma function evaluated at $x$.

source
Base.Math.lgammaMethod.
lgamma(x::arb)

Return the logarithm of the Gamma function evaluated at $x$.

source
Nemo.rgammaMethod.
rgamma(x::arb)

Return the reciprocal of the Gamma function evaluated at $x$.

source
Nemo.digammaMethod.
digamma(x::arb)

Return the logarithmic derivative of the gamma function evaluated at $x$, i.e. $\psi(x)$.

source
Nemo.zetaMethod.
zeta(x::arb)

Return the Riemann zeta function evaluated at $x$.

source
Base.Math.sincosMethod.
sincos(x::arb)

Return a tuple $s, c$ consisting of the sine $s$ and cosine $c$ of $x$.

source
Nemo.sincospiMethod.
sincospi(x::arb)

Return a tuple $s, c$ consisting of the sine $s$ and cosine $c$ of $\pi x$.

source
Base.Math.sinpiMethod.
sinpi(x::fmpq, r::ArbField)

Return the sine of $\pi x$ in the given Arb field.

source
Base.Math.cospiMethod.
cospi(x::fmpq, r::ArbField)

Return the cosine of $\pi x$ in the given Arb field.

source
Nemo.sincospiMethod.
sincospi(x::fmpq, r::ArbField)

Return a tuple $s, c$ consisting of the sine and cosine of $\pi x$ in the given Arb field.

source
Nemo.sinhcoshMethod.
sinhcosh(x::arb)

Return a tuple $s, c$ consisting of the hyperbolic sine and cosine of $x$.

source
Base.Math.atan2Method.
atan2(x::arb, y::arb)

Return atan2$(b,a) = \arg(a+bi)$.

source
Nemo.agmMethod.
agm(x::arb, y::arb)

Return the arithmetic-geometric mean of $x$ and $y$

source
Nemo.zetaMethod.
zeta(s::arb, a::arb)

Return the Hurwitz zeta function $\zeta(s,a)$.

source
Base.Math.hypotMethod.
hypot(x::arb, y::arb)

Return $\sqrt{x^2 + y^2}$.

source
Nemo.rootMethod.
root(x::arb, n::Int)

Return the $n$-th root of $x$. We require $x \geq 0$.

source
Nemo.facMethod.
fac(x::arb)

Return the factorial of $x$.

source
Nemo.facMethod.
fac(n::Int, r::ArbField)

Return the factorial of $n$ in the given Arb field.

source
Nemo.binomMethod.
binom(x::arb, n::UInt)

Return the binomial coefficient ${x \choose n}$.

source
Nemo.binomMethod.
binom(n::UInt, k::UInt, r::ArbField)

Return the binomial coefficient ${n \choose k}$ in the given Arb field.

source
Nemo.fibMethod.
fib(n::fmpz, r::ArbField)

Return the $n$-th Fibonacci number in the given Arb field.

source
Nemo.fibMethod.
fib(n::Int, r::ArbField)

Return the $n$-th Fibonacci number in the given Arb field.

source
Base.Math.gammaMethod.
gamma(x::fmpz, r::ArbField)

Return the Gamma function evaluated at $x$ in the given Arb field.

source
Base.Math.gammaMethod.
gamma(x::fmpq, r::ArbField)

Return the Gamma function evaluated at $x$ in the given Arb field.

source
Nemo.zetaMethod.
zeta(n::Int, r::ArbField)

Return the Riemann zeta function $\zeta(n)$ as an element of the given Arb field.

source
Nemo.bernoulliMethod.
bernoulli(n::Int, r::ArbField)

Return the $n$-th Bernoulli number as an element of the given Arb field.

source
Nemo.risingfacMethod.
risingfac(x::arb, n::Int)

Return the rising factorial $x(x + 1)\ldots (x + n - 1)$ as an Arb.

source
Nemo.risingfacMethod.
risingfac(x::fmpq, n::Int, r::ArbField)

Return the rising factorial $x(x + 1)\ldots (x + n - 1)$ as an element of the given Arb field.

source
Nemo.risingfac2Method.
risingfac2(x::arb, n::Int)

Return a tuple containing the rising factorial $x(x + 1)\ldots (x + n - 1)$ and its derivative.

source
Nemo.polylogMethod.
polylog(s::arb, a::arb)

Return the polylogarithm Li$_s(a)$.

source
Nemo.polylogMethod.
polylog(s::Int, a::arb)

Return the polylogarithm Li$_s(a)$.

source
chebyshev_t(n::Int, x::arb)

Return the value of the Chebyshev polynomial $T_n(x)$.

source
chebyshev_u(n::Int, x::arb)

Return the value of the Chebyshev polynomial $U_n(x)$.

source
Nemo.chebyshev_t2Method.
chebyshev_t2(n::Int, x::arb)

Return the tuple $(T_{n}(x), T_{n-1}(x))$.

source
Nemo.chebyshev_u2Method.
chebyshev_u2(n::Int, x::arb)

Return the tuple $(U_{n}(x), U_{n-1}(x))$

source
Nemo.bellMethod.
bell(n::fmpz, r::ArbField)

Return the Bell number $B_n$ as an element of $r$.

source
Nemo.bellMethod.
bell(n::Int, r::ArbField)

Return the Bell number $B_n$ as an element of $r$.

source
Nemo.numpartMethod.
numpart(n::fmpz, r::ArbField)

Return the number of partitions $p(n)$ as an element of $r$.

source
Nemo.numpartMethod.
numpart(n::fmpz, r::ArbField)

Return the number of partitions $p(n)$ as an element of $r$.

source

Examples

RR = RealField(64)

a = floor(exp(RR(1)))
b = sinpi(QQ(5,6), RR)
c = gamma(QQ(1,3), RealField(256))
d = bernoulli(1000, RealField(53))
f = polylog(3, RR(-10))

Linear dependence

Nemo.lindepMethod.
lindep(A::Array{arb, 1}, bits::Int)

Find a small linear combination of the entries of the array $A$ that is small *using LLL). The entries are first scaled by the given number of bits before truncating to integers for use in LLL. This function can be used to find linear dependence between a list of real numbers. The algorithm is heuristic only and returns an array of Nemo integers representing the linear combination.

source

Examples

RR = RealField(128)

a = RR(-0.33198902958450931620250069492231652319)

V = [RR(1), a, a^2, a^3, a^4, a^5]
W = lindep(V, 20)