arb-class: Arbitrary Precision Floating-Point Real Numbers with Error Bounds

Description

Class arb extends virtual class flint. It represents vectors of arbitrary precision floating-point real numbers with error bounds. Elements are specified by a pair of mixed format floating-point numbers: an arf midpoint and a mag radius.

Arithmetic on arb vectors is midpoint-radius interval arithmetic, also known as ball arithmetic, enabling computation with rigorous propagation of errors. Logic and comparison involving arb vectors are defined as follows: unary op(x) is true if and only if op is true for all elements of the interval x, and binary op(x, y) is true if and only if op is true for all elements of the Cartesian product of the intervals x and y. A corollary is that the operator <= does not define a total order on the range of arb (that is, the set of intervals \([m-r,m+r]\)), and a consequence is that methods for generic functions that necessitate a total order tend to signal an error.

Usage

## Class generator functions
arb(x = 0, length = 0L, names = NULL, mid = 0, rad = 0,
    prec = NULL)
arb.array(x = 0, dim = length(x), dimnames = NULL, mid = 0, rad = 0,
          prec = NULL)

Value

An arb vector, possibly an array; see ‘Details’.

Arguments

x: an atomic or flint vector containing data for conversion to arb.
length: a numeric vector of length one giving the length of the return value. If that exceeds the length of x, then x is recycled. Non-integer values are rounded in the direction of zero.
names: the names slot of the return value, either NULL or a character vector of equal length. Non-character names are coerced to character.
dim: the dim slot of the return value, an integer vector of nonzero length. If the product exceeds the length of x, then x is recycled. Non-integer numeric dim are coerced to integer.
dimnames: the dimnames slot of the return value, either NULL or a list of length equal to the length of dim. The components are either NULL or character vectors of length given by dim. Non-character vector components of dimnames are coerced to character.
mid, rad: atomic or flint vectors containing data for conversion to arf and mag, respectively. Use these for initialization “by parts” (midpoint and radius).
prec: the precision used for conversion of midpoints. NULL means to convert exactly if possible and to round to the global default precision otherwise; see flintPrec.

Conversion

Real numbers and real parts of complex numbers are rounded according to the precision set by prec, always in the direction of zero. Ball midpoints are the numbers obtained by rounding. Ball radii are upper bounds on the absolute errors incurred by rounding. Imaginary parts of complex numbers are discarded.

Character strings are scanned for format "s(km+/-r)", where k and m define the sign and absolute value of the signed ball midpoint, and r defines the unsigned ball radius. k can be empty if the ball midpoint is NaN or non-negative. s is an optional unary plus or minus to be reconciled with k.

The sequences km and r are converted using function mpfr_strtofr from the GNU MPFR library with argument base set to 0; see https://www.mpfr.org/mpfr-current/mpfr.html#Assignment-Functions.

Slots

.xData, dim, dimnames, names: inherited from virtual class flint.

Methods

Due to constraints imposed by generic functions, methods typically do not provide a formal argument prec allowing for a precision to be indicated in the function call. Such methods use the current default precision set by flintPrec.

!: signature(x = "arb"):
equivalent to (but faster than) x == 0.
%*%, crossprod, tcrossprod: signature(x = "arb", y = "arb"):
signature(x = "arb", y = "ANY"):
signature(x = "ANY", y = "arb"):
matrix products. The “other” operand must be atomic or inherit from virtual class flint. crossprod and tcrossprod behave as if y = x when y is missing or NULL. Operands are promoted as necessary and must be conformable (have compatible dimensions). Non-array operands of length k are handled as 1-by-k or k-by-1 matrices depending on the call.
+: signature(e1 = "arb", e2 = "missing"):
returns a copy of the argument.
-: signature(e1 = "arb", e2 = "missing"):
returns the negation of the argument.
Complex: signature(z = "arb"):
mathematical functions of one argument; see S4groupGeneric.
Math: signature(x = "arb"):
mathematical functions of one argument; see S4groupGeneric.
Math2: signature(x = "arb"):
decimal rounding according to a second argument digits; see S4groupGeneric. There are just two member member functions: round, signif.
Ops: signature(e1 = "arb", e2 = "arb"):
signature(e1 = "arb", e2 = "ANY"):
signature(e1 = "ANY", e2 = "arb"):
binary arithmetic, comparison, and logical operators; see S4groupGeneric. The “other” operand must be atomic or inherit from virtual class flint. Operands are promoted as necessary. Array operands must be conformable (have identical dimensions). Non-array operands are recycled.
Summary: signature(x = "arb"):
univariate summary statistics; see S4groupGeneric. The return value is a logical vector of length 1 (any, all) or an arb vector of length 1 or 2 (sum, prod, min, max, range).
anyNA: signature(x = "arb"):
returns TRUE if any element of x has midpoint NaN, FALSE otherwise.
as.vector: signature(x = "arb"):
returns as.vector(y, mode), where y is a double vector containing the result of converting the midpoints of x to the range of double, rounding if the value is not exactly representable in double precision. The rounding mode is to the nearest representable number (with precedence to even significands in case of ties), unless a midpoint exceeds .Machine[["double.xmax"]] in absolute value, in which case -Inf or Inf is introduced with a warning. Coercion to types "character", "symbol" (synonym "name"), "pairlist", "list", and "expression", which are not “number-like”, is handled specially. See also asVector.
backsolve: signature(r = "arb", x = "arb"):
signature(r = "arb", x = "ANY"):
signature(r = "ANY", x = "arb"):
solution of the triangular system op2(op1(r)) %*% y = x, where op1=ifelse(upper.tri, triu, tril) and op2=ifelse(transpose, t, identity) and upper.tri and transpose are optional logical arguments with default values TRUE and FALSE, respectively. The “other” operand must be atomic or inherit from virtual class flint. If x is missing, then the return value is the inverse of op2(op1(r)), as if x were the identity matrix. Operands are promoted as necessary and must be conformable (have compatible dimensions). Non-array x are handled as length(x)-by-1 matrices.
chol: signature(x = "arb"):
returns the upper triangular Cholesky factor of the positive definite matrix whose upper triangular part is the upper triangular part of x.
chol2inv: signature(x = "arb"):
returns the inverse of the positive definite matrix whose upper triangular Cholesky factor is the upper triangular part of x.
coerce: signature(from = "ANY", to = "arb"):
returns the value of arb(from).
colSums, colMeans: signature(x = "arb"):
returns an arb vector or array containing the column sums or means of x, defined as sums or means over dimensions 1:dims.
det: signature(x = "arb"):
returns the determinant of x as an arb vector of length 1.
determinant: signature(x = "arb"):
returns a list with components modulus and sign specifying the determinant of x, following the documented behaviour of the base function. The sign is NA if the interval computed by det(x) contains both negative numbers and positive numbers.
diff: signature(x = "arb"):
returns a vector storing lagged differences of the elements of x or (if x is a matrix) a matrix storing lagged differences of the rows of x, following the documented behaviour of the S3 default method.
diffinv: signature(x = "arb"):
returns the vector or matrix y such that x = diff(y, ...), following the documented behaviour of the S3 default method.
format: signature(x = "arb"):
returns a character vector suitable for printing, using string format "(m +/- r)" and scientific format for m and r. Optional arguments control the output; see format-methods.
is.finite: signature(x = "arb"):
returns a logical vector indicating which elements of x do not have midpoint NaN, -Inf, or Inf or radius Inf.
is.infinite: signature(x = "arb"):
returns a logical vector indicating which elements of x have midpoint -Inf or Inf or radius Inf.
is.na, is.nan: signature(x = "arb"):
returns a logical vector indicating which elements of x have midpoint NaN.
is.unsorted: signature(x = "arb"):
signals an error indicating that <= is not a total order on the range of arb; see xtfrm below.
log: signature(x = "arb"):
returns the logarithm of the argument. The natural logarithm is computed by default (when optional argument base is unset).
mean: signature(x = "arb"):
returns the arithmetic mean.
rowSums, rowMeans: signature(x = "arb"):
returns an arb vector or array containing the row sums or means of x, defined as sums or means over dimensions (dims+1):length(dim(x)).
solve: signature(a = "arb", b = "arb"):
signature(a = "arb", b = "ANY"):
signature(a = "ANY", b = "arb"):
solution of the general system a %*% x = b. The “other” operand must be atomic or inherit from virtual class flint. If b is missing, then the return value is the inverse of a, as if b were the identity matrix. Operands are promoted as necessary and must be conformable (have compatible dimensions). Non-array b are handled as length(b)-by-1 matrices.
xtfrm: signature(x = "arb"):
signals an error indicating that <= is not a total order on the range of arb: a <= b || b <= a is is not TRUE for all finite a and b of class arb. Thus, direct sorting of arb is not supported. Users wanting to order the midpoints should operate on Mid(x).

Details

The class generator function has six distinct usages:

arb()
arb(length=)
arb(x)
arb(x, length=)
arb(mid=, mid=)
arb(mid=, mid=, length=)

The first usage generates an empty vector. The second usage generates a zero vector of the indicated length. The third usage converts x, preserving dimensions, dimension names, and names. The fourth usage converts x, recycling its elements to the indicated length and discarding its dimensions, dimension names, and names. The fifth and sixth usages, in which either of mid and rad can be missing, use arf(mid) and mag(rad) to separately initialize the midpoints and radii of the arb return value.

Attempts to recycle mid, rad, or x of length zero to nonzero length are an error.

Usage of arb.array is modelled after array.

References

The FLINT documentation of the underlying C type: https://flintlib.org/doc/arb.html

Johansson, F. (2017). Arb: efficient arbitrary-precision midpoint-radius interval arithmetic. IEEE Transactions on Computers, 66(8), 1281-1292. tools:::Rd_expr_doi("10.1109/TC.2017.2690633")

Examples

Run this code

showClass("arb")
showMethods(classes = "arb")

Run the code above in your browser using DataLab