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)
mag.array(x = 0, dim = length(x), dimnames = 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.

Conversion

Magnitudes of real numbers and real parts of complex numbers are rounded in the direction of 0 or Inf according to the default rounding mode set by flintRnd. Imaginary parts of complex numbers are discarded.

Character strings are converted using function mpfr_strtofr from the GNU MPFR library with argument base set to 0 and argument rnd set according to the default rounding mode; 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

!: 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"):
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 = "mag", e2 = "missing"):
returns a copy of the argument.
-: signature(e1 = "mag", e2 = "missing"):
returns a copy of the argument, to be consistent with the binary operation which returns an upper bound for the absolute value of the difference.
Complex: signature(z = "mag"):
mathematical functions of one argument; see S4groupGeneric. The return value is an upper bound for the absolute value of the exact answer.
Math: signature(x = "mag"):
mathematical functions of one argument; see S4groupGeneric. The return value is an upper bound for the absolute value of the exact answer. Notably, the (inverse) trigonometric, (inverse) hyperbolic, and gamma-related member functions are not yet implemented. Users wanting those can (for now) operate on arb(x).
Math2: signature(x = "mag"):
decimal rounding according to a second argument digits; see S4groupGeneric. There are just two member functions: round, signif. The return value is an upper bound for the exact answer.
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 only if both operands are mag vectors. In that case, the return value is an upper bound for the absolute value of the exact answer. Users wanting “standard” floating-point arithmetic must ensure that at least one operand is not a mag vector.
Summary: signature(x = "mag"):
univariate summary statistics; see S4groupGeneric. The return value is a logical vector of length 1 (any, all) or an mag vector of length 1 or 2 (sum, prod, min, max, range). For sum and prod, the return value is an upper bound for the exact answer.
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 in the direction of Inf, not always to nearest. 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 upper bounds on the column sums or means of x, defined as sums or means over dimensions 1:dims.
det, determinant: 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 an upper bound for the absolute value of the logarithm of the argument. The natural logarithm is computed by default (when optional argument base is unset).
mean: signature(x = "mag"):
returns an upper bound for the arithmetic mean.
rowSums, rowMeans: signature(x = "mag"):
returns a mag vector or array containing upper bounds on 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")

Run the code above in your browser using DataLab