Rmpfr: mpfr-utils – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

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 class '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 class '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'))
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()

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 <= b <= 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`	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).

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.

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_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

Note

mpfrXport() and mpfrImport() are experimental and used to explore reported platform incompatibilities of save()d and load()ed "mpfr" objects between Windows and non-Windows platforms.

In other words, the format of the result of mpfrXport() and hence the mxp argument to mpfrImport() are considered internal, not part of the API and subject to change.

Examples

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 "current" MPFR versions:
eLimits == c(-1,1, -1,1) * (2^62 - 1)


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

i8 <- mpfr(-2:5, 32)
x4 <- mpfr(c(NA, NaN, -Inf, Inf), 32)
## The output of the following depends on the GMP "numb" size
## (32 bit vs. 64 bit), and may be even more platform specifics:
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))))
if(FALSE) ## FIXME: not yet working:
  stopifnot(identical(B6, mpfrImport(mpfrXport(B6))))

Rmpfr

R MPFR - Multiple Precision Floating-Point Reliable

v0.8-4

GPL (>= 2)

Authors

Martin Maechler [aut, cre] (<https://orcid.org/0000-0002-8685-9910>), Richard M. Heiberger [ctb] (formatHex(), *Bin, *Dec), John C. Nash [ctb] (hjkMpfr(), origin of unirootR()), Hans W. Borchers [ctb] (optimizeR(*, "GoldenRatio"); origin of hjkMpfr())

Initial release

2021-04-08