mag-class: Fixed Precision Magnitude (Error) Bounds

Description

Class mag extends virtual class flint. It represents vectors of fixed precision error bounds. Elements are unsigned floating-point numbers with a 30-bit significand and an arbitary precision exponent. The underlying C type can represent Inf but not NaN.

Usage

## Class generator functions
mag(x = 0, length = 0L, names = NULL, rnd.mag = NULL)
mag.array(x = 0, dim = length(x), dimnames = NULL, rnd.mag = NULL)

Value

A mag vector, possibly an array; see ‘Details’.

Arguments

x: an atomic or flint vector containing data for conversion to mag.
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.
rnd.mag: the rounding mode used for inexact conversion. NULL means to round according to the global default rounding mode; see flintRndMag.

Conversion

Magnitudes of real numbers and real parts of complex numbers are rounded towards or away from zero according to the rounding mode set by rnd.mag. Imaginary parts of complex numbers are discarded.

It is guaranteed that the result of conversion is a lower or upper bound on the converted value. It is not guaranteed that the bound is optimal; in particular, the result of conversion can be inexact even if the converted value is exactly representable. Indeed, the computed bound and the optimal bound can differ by several ulps. If that seems unusual, then note that mag exists primarily to represent the radii of arb and acb, and arithmetic involving arb or acb benefits from fast and “precise enough” operations on the radii.

Character strings 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.

An error is signaled if elements of x are NaN.

Slots

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

Methods

Methods that return a mag vector are below marked by an asterisk * after signature(...). Where the generic function is defined as evaluating a real-valued mathematical function \(F\), these methods compute lower or upper bounds on \(|F|\). In this sense, the marked methods can be seen as violating the generic function's “contract”. For contract-adhering behaviour, dispatch methods for arf, e.g., do log(arf(x)) instead of log(x) for x of class mag. The bounds computed by the marked methods are not optimal in general; see ‘Conversion’. Whether lower (as opposed to upper) bounds are computed depends on the global default rounding mode; see flintRndMag.

!: signature(x = "mag"):
equivalent to (but faster than) x == 0.
%*%, crossprod, tcrossprod: signature(x = "mag", y = "mag"):
signature(x = "mag", y = "ANY"):
signature(x = "ANY", y = "mag"):
coerces the mag operand to class arf, acf, arb, or acb (depending on the class of the other operand) and dispatches.
+, -: signature(e1 = "mag", e2 = "missing")*:
returns a copy of the argument.
Complex: signature(z = "mag")*:
mathematical functions of one argument; see S4groupGeneric.
Math: signature(x = "mag")*:
mathematical functions of one argument; see S4groupGeneric.
Math2: signature(x = "mag")*:
decimal rounding according to a second argument digits; see S4groupGeneric. There are just two member functions: round, signif.
Ops: signature(e1 = "mag", e2 = "mag")*:
signature(e1 = "mag", e2 = "ANY"):
signature(e1 = "ANY", e2 = "mag"):
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. For arithmetic, the return value is a mag vector if and only if both operands are mag vectors.
Summary: signature(x = "mag")*:
univariate summary statistics; see S4groupGeneric. The return value is a logical vector of length 1 (any, all) or a mag vector of length 1 or 2 (sum, prod, min, max, range).
anyNA: signature(x = "mag"):
returns FALSE, as mag has no representation for NaN.
as.vector: signature(x = "mag"):
returns as.vector(y, mode), where y is a double vector containing the result of converting each element of x to the range of double, rounding away from zero though not always to the nearest greater number. 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 = "mag", x = "mag"):
signature(r = "mag", x = "ANY"):
signature(r = "ANY", x = "mag"):
coerces the mag operand to class arf, acf, arb, or acb (depending on the class of the other operand) and dispatches.
chol, chol2inv: signature(x = "mag"):
coerces x to class arf and dispatches.
coerce: signature(from = "ANY", to = "mag")*:
returns the value of mag(from).
colSums, colMeans: signature(x = "mag")*:
returns a mag vector or array containing the column sums or means of x, defined as sums or means over dimensions 1:dims.
det, determinant, diff, diffinv: signature(x = "mag"):
coerces x to class arf and dispatches.
format: signature(x = "mag"):
returns a character vector suitable for printing, using scientific format. Optional arguments control the output; see format-methods.
is.finite: signature(x = "mag"):
returns a logical vector indicating which elements of x are not Inf.
is.infinite: signature(x = "mag"):
returns a logical vector indicating which elements of x are Inf.
is.na, is.nan: signature(x = "mag"):
returns a logical vector whose elements are all FALSE, as mag has no representation for NaN.
is.unsorted: signature(x = "mag"):
returns a logical indicating if x is not sorted in nondecreasing order (increasing order if optional argument strictly is set to TRUE).
log: signature(x = "mag")*:
returns the logarithm of the argument. The natural logarithm is computed by default (when optional argument base is unset).
mean: signature(x = "mag")*:
returns the arithmetic mean.
rowSums, rowMeans: signature(x = "mag")*:
returns a mag 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 = "mag", b = "mag"):
signature(a = "mag", b = "ANY"):
signature(a = "ANY", b = "mag"):
coerces the mag operand to class arf, acf, arb, or acb (depending on the class of the other operand) and dispatches.

Details

The class generator function has four distinct usages:

mag()
mag(length=)
mag(x)
mag(x, 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. Attempts to recycle x of length zero to nonzero length are an error.

Usage of mag.array is modelled after array.

References

The FLINT documentation of the underlying C type: https://flintlib.org/doc/mag.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("mag")
showMethods(classes = "mag")

(ornd <- flintRndMag()) # getting the original rounding mode

## Output gives 4 significant digits by default
(magpi <- mag(pi))

## Number of reliable digits is 8 == floor((30 - 1) * log10(2))
as.character(magpi)

## Integers in range of 30-bit unsigned type are converted exactly
(x0 <- -1L:1L * (0x1p+30L - 1L))
mag(x0) == abs(x0) #     all TRUE
(x1 <- -1L:1L * (0x1p+30L - 0L))
mag(x1) == abs(x1) # not all TRUE

## Conversion of most other input is influenced by the rounding mode
flintRndMag("A")
mag( 1) >  1
mag(pi) > pi
flintRndMag("Z")
mag( 1) <  1
mag(pi) < pi

## Computing bounds on composite functions needs care;
## e.g., for an upper bound on abs(tan(2)) = sin(2)/abs(cos(2)):
tt <- mag(2L) # exact
flintRndMag("Z") # some quantities must be rounded towards 0
cos2 <- cos(tt)
flintRndMag("A") # others must be rounded away from 0
sin2 <- sin(tt)
tan2 <- sin2/cos2
tan2    - abs(tan(2))
tan(tt) - abs(tan(2)) # direct hence sharper

flintRndMag(ornd) # resetting the original rounding mode

Run the code above in your browser using DataLab