hypergeo2: Generalized Hypergeometric Function with Tunable High Precision

Description

Computation of generalized hypergeometric function with tunable high precision in a vectorized manner, with the floating-point datatypes from 'mpfr' or 'gmp' library. The computation is limited to real numbers.

Author(s)

Maintainer: Xiurui Zhu zxr6@163.com

See Also

Useful links:

• https://github.com/zhuxr11/hypergeo2

• Report bugs at https://github.com/zhuxr11/hypergeo2/issues

Generalized hypergeometric function

Description

genhypergeo computes generalized hypergeometric function with vectorized input.

Usage

genhypergeo(
  U,
  L,
  z,
  prec = NULL,
  check_mode = TRUE,
  log = FALSE,
  backend = c("mpfr", "gmp")
)

Arguments

Details

Sometimes, computing generalized hypergeometric function in double precision is not sufficient, even though we only need 6-8 accurate digits in the results (see example). Here, two floating-point datatypes are provided: mpfr_float ('mpfr') and gmp_float ('gmp'). By comparison, the 'mpfr' backend is safer, since it defines Inf while the 'gmp' backend throws overflow exception (see references). But the 'gmp' backend results in more accurate results at the same precision, since it usually uses higher precision than set (see reference and validate it on yourself with the examples).

genhypergeo is available in Rcpp as hypergeo2::genhypergeo_vec(); its non-vectorized version is named in Rcpp as hypergeo2::genhypergeo_cpp().

Its non-vectorized version is available in Rcpp as hypergeo2::genhypergeo_<int SXP, typename T1, typename T2>(), where SXP is the type of Rcpp::Vector, T1 is the input/output datatype and T2 is the datatype used in computation (see references for example datatypes).

To use them, please use [[Rcpp::depends(hypergeo2)]] and #include <hypergeo2.h> in your C++ source files, and add @importFrom hypergeo2 genhypergeo to R/*-package.R file, just like Rcpp.

Value

Numeric vector as the results of computation (at double precision). Warnings are issued if failing to converge.

Note

Change log:

• 0.1.0 Xiurui Zhu - Initiate the function.

Author(s)

Xiurui Zhu

References

For the floating-point datatypes of tunable precision:

• Documentation about mpfr_float, with datatype boost::multiprecision::number<boost::multiprecision::backends::mpfr_float_backend<0>>

• Documentation about gmp_float, with datatype boost::multiprecision::number<boost::multiprecision::backends::gmp_float<0>>

• Documentation about higher precision of gmp_float datatype

Examples

U <- c(-28.2, 11.8, 15.8)
L <- c(12.8, 17.8)
z <- 1
# hypergeo results
if (length(find.package("hypergeo", quiet = TRUE)) > 0L) {
  hypergeo::genhypergeo(U = U, L = L, z = z)
}
# Default (double) precision: this may result in cancellation error on some platforms
tryCatch(
  genhypergeo(U = U, L = L, z = z),
  error = function(err) {
    if (grepl("Cancellation is so severe that no bits in the result are correct",
              conditionMessage(err)) == TRUE) {
      message("! Cancellation error on your platform: ",
              "you may need a higher [prec] than double ([prec = NULL]): ",
              conditionMessage(err))
    } else {
      stop(err)
    }
  }
)
# Precision of 20 digits, default ('mpfr') backend
genhypergeo(U = U, L = L, z = z, prec = 20L)
# Precision of 20 digits, 'gmp' backend
genhypergeo(U = U, L = L, z = z, prec = 20L, backend = "gmp")
# Precision of 25 digits, default ('mpfr') backend
genhypergeo(U = U, L = L, z = z, prec = 25L)
# Precision of 25 digits, 'gmp' backend
genhypergeo(U = U, L = L, z = z, prec = 25L, backend = "gmp")