mpfr-utils: Rmpfr -- Utilities for Precision Setting, Printing, etc

Description

This page documents utilities from package Rmpfr which are typically not called by the user, but may come handy in some situations.

Notably, the (base-2) maximal (and minimal) precision and the “erange”, the range of possible (base-2) exponents of mpfr-numbers can be queried and partly extended.

Usage

getPrec(x, base = 10, doNumeric = TRUE, is.mpfr = NA, bigq. = 128L)
.getPrec(x)
getD(x)
mpfr_default_prec(prec)
# S3 method for mpfrArray
print(x, digits = NULL, drop0trailing = FALSE,
      right = TRUE,
      max.digits = getOption("Rmpfr.print.max.digits", 999L),
      exponent.plus = getOption("Rmpfr.print.exponent.plus", TRUE),
      ...)
# S3 method for mpfr
print(x, digits = NULL, drop0trailing = TRUE,
      right = TRUE,
      max.digits = getOption("Rmpfr.print.max.digits", 999L),
      exponent.plus = getOption("Rmpfr.print.exponent.plus", TRUE),
      ...)
toNum(from, rnd.mode = c('N','D','U','Z','A'))
.mpfr2d(from)
.mpfr2i(from)
mpfr2array(x, dim, dimnames = NULL, check = FALSE)
.mpfr2list(x, names = FALSE)
mpfrXport(x, names = FALSE)
mpfrImport(mxp)
.mpfr_formatinfo(x)
.mpfr2exp(x)
.mpfr_erange(kind = c("Emin", "Emax"), names = TRUE)
.mpfr_erange_set(kind = c("Emin", "Emax"), value)
.mpfr_erange_kinds
.mpfr_erange_is_int()
.mpfr_maxPrec()
.mpfr_minPrec()
.mpfr_gmp_numbbits()
.mpfrVersion()
## Really Internal and low level, no error checking (for when you know ..)
.mpfr (x, precBits)
.mpfr.(x, precBits, rnd.mode)
.getSign(x)
.mpfr_negative(x)
.mpfr_sign(x)
..bigq2mpfr(x, precB = NULL, rnd.mode = c("N", "D", "U", "Z", "A"))
..bigz2mpfr(x, precB = NULL, rnd.mode = c("N", "D", "U", "Z", "A"))

Value

getPrec(x) returns a integer vector of length one or the same length as x when that is positive, whereas

getPrec(NULL) returns mpfr_default_prec(), see below.

If you need to change the precision of x, i.e., need something like “setPrec”, use roundMpfr().

.getPrec(x) is a simplified version of getPrec() which only works for "mpfr" objects x.

getD(x) is intended to be a fast version of x@.Data, and should not be used outside of lower level functions.

mpfr_default_prec() returns the current MPFR default precision, an integer. This is currently

not made use of much in package Rmpfr, where functions have their own default precision where needed, and otherwise we'd rather not be dependent of such a global setting.

mpfr_default_prec(prec)

sets the current MPFR default precision and returns the previous one; see above.

.mpfr_maxPrec() and (less interestingly) .mpfr_minPrec()

give the maximal and minimal base-2 precision allowed in the current version of the MPFR library linked to by R package Rmpfr. The maximal precision is typically $2^{63}$, i.e.,

 all.equal(.mpfr_maxPrec(), 2^63)

is typically true.

toNum(m) returns a numeric array or

matrix, when m is of class

"mpfrArray" or "mpfrMatrix", respectively. It should be equivalent to as(m, "array") or

... "matrix". Note that the slightly more general

asNumeric() is preferred now.

.mpfr2d() is similar to but simpler than toNum(), whereas

.mpfr2i() is an analogue low level utility for

as.integer(<mpfr>).

mpfr2array() a slightly more flexible alternative to

dim(.) <- dd.

.mpfr2exp(x) returns the base-2 (integer valued) exponents of

x, i.e., it is the R interface to MPFR C's mpfr_get_exp(). The result is integer iff .mpfr_erange_is_int()

is true, otherwise double. Note that the MPFR (4.0.1) manual says about mpfr_get_exp(): The behavior for NaN, infinity or zero is undefined.

.mpfr_erange_is_int() returns TRUE iff the

.mpfr_erange(c("Emin","Emax")) range lies inside the range of R's

integer limits, i.e., has absolute values not larger than

.Machine$integer.max ($ = 2^{31} - 1$).

.mpfr_erange_set()

invisibly (see invisible()) returns TRUE iff the change was successful.

.mpfr_gmp_numbbits() returns the GMP library “numb”

size, which is either 32 or 64 bit (as integer, i.e.,

64L or 32L). If it is not 64, you typically cannot enlarge the exponential range of mpfr numbers via

.mpfr_erange(), see above.

.mpfrVersion() returns a string, the version of the MPFR

library we are linking to.

.mpfr_formatinfo(x) returns conceptually a subset of

.mpfr2str()'s result, a list with three components

exp: the base-2 exponents of x, identical to .mpfr2exp(x).
finite: logical identical to is.finite(x).
is.0: logical indicating if the corresponding x[i] is zero; identical to mpfrIs0(x).

(Note that .mpfr2str(x, .., base)$exp is wrt base

and is not undefined but ...)

.mpfr_sign(x) only works for mpfr objects, then identical to sign(x). Analogously, .mpfr_negative(x) is

-x in that case.

.getSign(x) is a low-level version of sign(x)

returning -1 or +1, but not 0.

Finally, ..bigq2mpfr(x, ..) and ..bigz2mpfr(x, ..) are fast ways to coerce bigz and bigq number objects (created by package gmp's functionality) to our "mpfr" class.

Arguments

x, from: typically, an R object of class "mpfr", or "mpfrArray", respectively. For getPrec(), any number-like R object, or NULL.
base: (only when x is character) the base with respect to which x[i] represent numbers; base $b$ must fulfill $2 \le b \le 62$.
doNumeric: logical indicating integer or double typed x should be accepted and a default precision be returned. Should typically be kept at default TRUE.
is.mpfr: logical indicating if class(x) is already known to be "mpfr"; typically should be kept at default, NA.
bigq.: for getPrec(), the precision to use for a big rational (class "bigq"); if not specified gives warning when used.
prec, precB, precBits: a positive integer, or missing.
drop0trailing: logical indicating if trailing "0"s should be omitted.
right: logical indicating print()ing should right justify the strings; see print.default() to which it is passed.
digits, ...: further arguments to print methods.
max.digits: a number (possibly Inf) to limit the number of (mantissa) digits to be printed, simply passed to formatMpfr(). The default is finite to protect from printing very long strings which is often undesirable, notably in interactive use.
exponent.plus: logical, simply passed to formatMpfr(). Was FALSE hardwired in Rmpfr versions before 0.8-0, and hence is allowed to be tweaked by an options() setting.
rnd.mode: a 1-letter string specifying how rounding should happen at C-level conversion to MPFR, see details of mpfr.
dim, dimnames: for "mpfrArray" construction.
check: logical indicating if the mpfrArray construction should happen with internal safety check. Previously, the implicit default used to be true.
names: (for .mpfr2list()) logical or character vector, indicating if the list returned should have names. If character, it specifies the names; if true, the names are set to format(x).
mxp: an "mpfrXport" object, as resulting from mpfrXport().
kind: a character string or vector, specifying the kind of “erange” value; must be an element of .mpfr_erange_kinds, i.e., one of "Emin", "Emax", "min.emin", "max.emin", "min.emax", "max.emax".
value: numeric, for .mpfr_erange_set() one number per kind. Must be in range specified by the *."emin" and *."emax" erange values.

Details

The print method is currently built on the format method for class mpfr. This, currently does not format columns jointly which leads to suboptimally looking output. There are plans to change this.

Note that formatMpfr() which is called by print() (or show() or R's implicit printing) uses max.digits = Inf, differing from our print()'s default on purpose. If you do want to see the full accuracy even in cases it is large, use options(Rmpfr.print.max.digits = Inf) or (.. = 1e7), say.

The .mpfr_erange* functions (and variable) allow to query and set the allowed range of values for the base-2 exponents of "mpfr" numbers. See the examples below and GNU MPFR library documentation on the C functions mpfr_get_emin(), mpfr_set_emin(.), mpfr_get_emin_min(), and mpfr_get_emin_max(), (and those four with ‘_emin’ replaced by ‘_emax’ above).

Examples

Run this code

getPrec(as(c(1,pi), "mpfr")) # 128 for both

(opr <- mpfr_default_prec()) ## typically  53, the MPFR system default
stopifnot(opr == (oprec <- mpfr_default_prec(70)),
          70  == mpfr_default_prec())
## and reset it:
mpfr_default_prec(opr)

## Explore behavior of rounding modes 'rnd.mode':
x <- mpfr(10,99)^512 # too large for regular (double prec. / numeric):
sapply(c("N", "D", "U", "Z", "A"), function(RM)
       sapply(list(-x,x), function(.) toNum(., RM)))
##    N             D              U              Z    A
## -Inf          -Inf -1.797693e+308 -1.797693e+308 -Inf
##  Inf 1.797693e+308            Inf  1.797693e+308  Inf

## Printing of "MPFR" matrices is less nice than R's usual matrix printing:
m <- outer(c(1, 3.14, -1024.5678), c(1, 1e-3, 10,100))
m[3,3] <- round(m[3,3])
m
mpfr(m, 50)

B6 <- mpfr2array(Bernoulli(1:6, 60), c(2,3),
                 dimnames = list(LETTERS[1:2], letters[1:3]))
B6

## Ranges of (base 2) exponents of MPFR numbers:
.mpfr_erange() # the currently active range of possible base 2 exponents:

## A factory fresh setting fulfills
.mpfr_erange(c("Emin","Emax")) == c(-1,1) * (2^30 - 1)

## There are more 'kind's, the latter 4 showing how you could change the first two :
.mpfr_erange_kinds
.mpfr_erange(.mpfr_erange_kinds)
eLimits <- .mpfr_erange(c("min.emin", "max.emin", "min.emax", "max.emax"))
## Typically true in MPFR versions *iff* long is 64-bit, i.e. *not* on Windows
if(.Machine$sizeof.long == 8L) {
    eLimits == c(-1,1, -1,1) * (2^62 - 1)
} else if(.Machine$sizeof.long == 4L) # on Windows
    eLimits == c(-1,1, -1,1) * (2^30 - 1)


## Looking at internal representation [for power users only!]:

i8 <- mpfr(-2:5, 32)
x4 <- mpfr(c(NA, NaN, -Inf, Inf), 32)
stopifnot(exprs = {
    identical(x4[1], x4[2])
    is.na(x4[1] == x4[2]) # <- was *wrong* in Rmpfr <= 0.9-4
    is.na(x4[1] != x4[2]) #  (ditto)
    identical(x4 < i8[1:4], c(NA,NA, TRUE,FALSE))
    !is.finite(x4)
    identical(is.infinite(x4), c(FALSE,FALSE, TRUE,TRUE))
})
## The output of the following depends on the GMP "numb" size
## (32 bit vs. 64 bit), *and* additionally
## on sizeof.long (mostly non-Windows <-> Windows, see above):
str( .mpfr2list(i8) )
str( .mpfr2list(x4, names = TRUE) )

str(xp4 <- mpfrXport(x4, names = TRUE))
stopifnot(identical(x4, mpfrImport(mpfrXport(x4))),
          identical(i8, mpfrImport(mpfrXport(i8))))
## FIXME, need c(.), as dim(.)  "get lost":
stopifnot(identical(c(B6), mpfrImport(mpfrXport(B6))))