Cubature Vectorization Results

Introduction

This R cubature package exposes both the hcubature and pcubature routines of the underlying C cubature library, including the vectorized interfaces.

Per the documentation, use of pcubature is advisable only for smooth integrands in dimensions up to three at most. In fact, the pcubature routines perform significantly worse than the vectorized hcubature in inappropriate cases. So when in doubt, you are better off using hcubature.

Version 2.0 of this package integrates the Cuba library as well, once again providing vectorized interfaces.

The main point of this note is to examine the difference vectorization makes. My recommendations are below in the summary section.

A Timing Harness

Our harness will provide timing results for hcubature, pcubature (where appropriate) and Cuba cuhre calls. We begin by creating a harness for these calls.

library(benchr)
library(cubature)

harness <- function(which = NULL,
                    f, fv, lowerLimit, upperLimit, tol = 1e-3, times = 20, ...) {

    fns <- c(hc = "Non-vectorized Hcubature",
             hc.v = "Vectorized Hcubature",
             pc = "Non-vectorized Pcubature",
             pc.v = "Vectorized Pcubature",
             cc = "Non-vectorized cubature::cuhre",
             cc_v = "Vectorized cubature::cuhre")
    cc <- function() cubature::cuhre(f = f,
                                     lowerLimit = lowerLimit, upperLimit = upperLimit,
                                     relTol = tol,
                                     ...)
    cc_v <- function() cubature::cuhre(f = fv,
                                       lowerLimit = lowerLimit, upperLimit = upperLimit,
                                       relTol = tol,
                                       nVec = 1024L,
                                       ...)

    hc <- function() cubature::hcubature(f = f,
                                         lowerLimit = lowerLimit,
                                         upperLimit = upperLimit,
                                         tol = tol,
                                         ...)

    hc.v <- function() cubature::hcubature(f = fv,
                                           lowerLimit = lowerLimit,
                                           upperLimit = upperLimit,
                                           tol = tol,
                                           vectorInterface = TRUE,
                                           ...)

    pc <- function() cubature::pcubature(f = f,
                                     lowerLimit = lowerLimit,
                                     upperLimit = upperLimit,
                                     tol = tol,
                                     ...)

    pc.v <- function() cubature::pcubature(f = fv,
                                           lowerLimit = lowerLimit,
                                           upperLimit = upperLimit,
                                           tol = tol,
                                           vectorInterface = TRUE,
                                           ...)
    
    ndim = length(lowerLimit)

    if (is.null(which)) {
        fnIndices <- seq_along(fns)
    } else {
        fnIndices <- na.omit(match(which, names(fns)))
    }
    fnList <- lapply(names(fns)[fnIndices], function(x) call(x))

    argList <- c(fnList, times = times, progress = FALSE)
    result <- do.call(benchr::benchmark, args = argList)
    d <- summary(result)[seq_along(fnIndices), ]
    d$expr <- fns[fnIndices]
    d
}

We reel off the timing runs.

Example 1.

func <- function(x) sin(x[1]) * cos(x[2]) * exp(x[3])
func.v <- function(x) {
    matrix(apply(x, 2, function(z) sin(z[1]) * cos(z[2]) * exp(z[3])), ncol = ncol(x))
}

d <- harness(f = func, fv = func.v,
             lowerLimit = rep(0, 3),
             upperLimit = rep(1, 3),
             tol = 1e-5,
             times = 100)
knitr::kable(d, digits = 3, row.names = FALSE)

expr	n.eval	min	lw.qu	median	mean	up.qu	max	total	relative
Non-vectorized Hcubature	100	0.001	0.001	0.001	0.001	0.001	0.001	0.078	1.26
Vectorized Hcubature	100	0.001	0.001	0.001	0.001	0.001	0.003	0.064	1.00
Non-vectorized Pcubature	100	0.002	0.002	0.002	0.002	0.002	0.004	0.246	3.97
Vectorized Pcubature	100	0.002	0.002	0.002	0.002	0.002	0.002	0.177	2.85
Non-vectorized cubature::cuhre	100	0.001	0.001	0.001	0.002	0.001	0.004	0.154	2.40
Vectorized cubature::cuhre	100	0.001	0.001	0.001	0.001	0.001	0.001	0.089	1.43

Multivariate Normal

Using cubature, we evaluate \[ \int_R\phi(x)dx \] where \(\phi(x)\) is the three-dimensional multivariate normal density with mean 0, and variance \[ \Sigma = \left(\begin{array}{rrr} 1 &\frac{3}{5} &\frac{1}{3}\\ \frac{3}{5} &1 &\frac{11}{15}\\ \frac{1}{3} &\frac{11}{15} & 1 \end{array} \right) \] and \(R\) is \([-\frac{1}{2}, 1] \times [-\frac{1}{2}, 4] \times [-\frac{1}{2}, 2].\)

We construct a scalar function (my_dmvnorm) and a vector analog (my_dmvnorm_v). First the functions.

m <- 3
sigma <- diag(3)
sigma[2,1] <- sigma[1, 2] <- 3/5 ; sigma[3,1] <- sigma[1, 3] <- 1/3
sigma[3,2] <- sigma[2, 3] <- 11/15
logdet <- sum(log(eigen(sigma, symmetric = TRUE, only.values = TRUE)$values))
my_dmvnorm <- function (x, mean, sigma, logdet) {
    x <- matrix(x, ncol = length(x))
    distval <- stats::mahalanobis(x, center = mean, cov = sigma)
    exp(-(3 * log(2 * pi) + logdet + distval)/2)
}

my_dmvnorm_v <- function (x, mean, sigma, logdet) {
    distval <- stats::mahalanobis(t(x), center = mean, cov = sigma)
    exp(matrix(-(3 * log(2 * pi) + logdet + distval)/2, ncol = ncol(x)))
}

Now the timing.

d <- harness(f = my_dmvnorm, fv = my_dmvnorm_v,
             lowerLimit = rep(-0.5, 3),
             upperLimit = c(1, 4, 2),
             tol = 1e-5,
             times = 10,
             mean = rep(0, m), sigma = sigma, logdet = logdet)
knitr::kable(d, digits = 3)

expr	n.eval	min	lw.qu	median	mean	up.qu	max	total	relative
Non-vectorized Hcubature	10	1.332	1.344	1.380	1.387	1.426	1.462	13.868	557.00
Vectorized Hcubature	10	0.003	0.003	0.003	0.004	0.004	0.004	0.035	1.40
Non-vectorized Pcubature	10	0.543	0.575	0.610	0.605	0.632	0.658	6.049	246.00
Vectorized Pcubature	10	0.002	0.002	0.002	0.002	0.003	0.003	0.024	1.00
Non-vectorized cubature::cuhre	10	0.530	0.536	0.582	0.579	0.598	0.688	5.789	235.00
Vectorized cubature::cuhre	10	0.005	0.005	0.006	0.006	0.007	0.009	0.062	2.36

The effect of vectorization is huge. So it makes sense for users to vectorize the integrands as much as possible for efficiency.

Furthermore, for this particular example, we expect mvtnorm::pmvnorm to do pretty well since it is specialized for the multivariate normal. The good news is that the vectorized versions of hcubature and pcubature are quite competitive if you compare the table above to the one below.

library(mvtnorm)
g1 <- function() pmvnorm(lower = rep(-0.5, m),
                                  upper = c(1, 4, 2), mean = rep(0, m), corr = sigma,
                                  alg = Miwa(), abseps = 1e-5, releps = 1e-5)
g2 <- function() pmvnorm(lower = rep(-0.5, m),
                         upper = c(1, 4, 2), mean = rep(0, m), corr = sigma,
                         alg = GenzBretz(), abseps = 1e-5, releps = 1e-5)
g3 <- function() pmvnorm(lower = rep(-0.5, m),
                         upper = c(1, 4, 2), mean = rep(0, m), corr = sigma,
                         alg = TVPACK(), abseps = 1e-5, releps = 1e-5)

knitr::kable(summary(benchr::benchmark(g1(), g2(), g3(), times = 20, progress = FALSE)),
             digits = 3, row.names = FALSE)

expr	n.eval	min	lw.qu	median	mean	up.qu	max	total	relative
g1()	20	0.001	0.001	0.002	0.002	0.002	0.005	0.035	1.01
g2()	20	0.001	0.001	0.002	0.002	0.002	0.005	0.035	1.00
g3()	20	0.001	0.002	0.002	0.002	0.002	0.004	0.035	1.00

Product of cosines

testFn0 <- function(x) prod(cos(x))
testFn0_v <- function(x) matrix(apply(x, 2, function(z) prod(cos(z))), ncol = ncol(x))

d <- harness(f = testFn0, fv = testFn0_v,
             lowerLimit = rep(0, 2), upperLimit = rep(1, 2), times = 1000)
knitr::kable(d, digits = 3)

expr	n.eval	min	lw.qu	median	mean	up.qu	max	total	relative
Non-vectorized Hcubature	1000	0.000	0.000	0.000	0.000	0.000	0.002	0.102	1.00
Vectorized Hcubature	1000	0.000	0.000	0.000	0.000	0.000	0.002	0.129	1.22
Non-vectorized Pcubature	1000	0.000	0.000	0.000	0.000	0.000	0.002	0.134	1.32
Vectorized Pcubature	1000	0.000	0.000	0.000	0.000	0.000	0.003	0.226	2.21
Non-vectorized cubature::cuhre	1000	0.001	0.001	0.001	0.001	0.001	0.046	0.914	8.61
Vectorized cubature::cuhre	1000	0.001	0.001	0.001	0.001	0.001	0.003	0.614	5.95

Gaussian function

testFn1 <- function(x) {
    val <- sum(((1 - x) / x)^2)
    scale <- prod((2 / sqrt(pi)) / x^2)
    exp(-val) * scale
}

testFn1_v <- function(x) {
    val <- matrix(apply(x, 2, function(z) sum(((1 - z) / z)^2)), ncol(x))
    scale <- matrix(apply(x, 2, function(z) prod((2 / sqrt(pi)) / z^2)), ncol(x))
    exp(-val) * scale
}

d <- harness(f = testFn1, fv = testFn1_v,
             lowerLimit = rep(0, 3), upperLimit = rep(1, 3), times = 10)

knitr::kable(d, digits = 3)

expr	n.eval	min	lw.qu	median	mean	up.qu	max	total	relative
Non-vectorized Hcubature	10	0.006	0.007	0.007	0.007	0.007	0.007	0.068	30.00
Vectorized Hcubature	10	0.007	0.007	0.008	0.008	0.008	0.009	0.077	33.60
Non-vectorized Pcubature	10	0.000	0.000	0.000	0.000	0.000	0.000	0.002	1.00
Vectorized Pcubature	10	0.000	0.000	0.000	0.000	0.000	0.000	0.003	1.46
Non-vectorized cubature::cuhre	10	0.029	0.030	0.030	0.031	0.031	0.033	0.308	136.00
Vectorized cubature::cuhre	10	0.029	0.030	0.030	0.031	0.031	0.033	0.306	135.00

Discontinuous function

testFn2 <- function(x) {
    radius <- 0.50124145262344534123412
    ifelse(sum(x * x) < radius * radius, 1, 0)
}

testFn2_v <- function(x) {
    radius <- 0.50124145262344534123412
    matrix(apply(x, 2, function(z) ifelse(sum(z * z) < radius * radius, 1, 0)), ncol = ncol(x))
}

d <- harness(which = c("hc", "hc.v", "cc", "cc_v"),
             f = testFn2, fv = testFn2_v,
             lowerLimit = rep(0, 2), upperLimit = rep(1, 2), times = 10)
knitr::kable(d, digits = 3)

expr	n.eval	min	lw.qu	median	mean	up.qu	max	total	relative
Non-vectorized Hcubature	10	0.089	0.090	0.092	0.093	0.095	0.104	0.933	1.12
Vectorized Hcubature	10	0.074	0.080	0.082	0.086	0.084	0.117	0.857	1.00
Non-vectorized cubature::cuhre	10	1.705	1.717	1.729	1.732	1.744	1.773	17.322	21.00
Vectorized cubature::cuhre	10	1.424	1.436	1.452	1.455	1.461	1.515	14.554	17.60

A Simple Polynomial (product of coordinates)

testFn3 <- function(x) prod(2 * x)
testFn3_v <- function(x) matrix(apply(x, 2, function(z) prod(2 * z)), ncol = ncol(x))

d <- harness(f = testFn3, fv = testFn3_v,
             lowerLimit = rep(0, 3), upperLimit = rep(1, 3), times = 50)
knitr::kable(d, digits = 3)

expr	n.eval	min	lw.qu	median	mean	up.qu	max	total	relative
Non-vectorized Hcubature	50	0.000	0.000	0.000	0.000	0.000	0.000	0.007	1.14
Vectorized Hcubature	50	0.000	0.000	0.000	0.000	0.000	0.000	0.008	1.19
Non-vectorized Pcubature	50	0.000	0.000	0.000	0.000	0.000	0.000	0.007	1.00
Vectorized Pcubature	50	0.000	0.000	0.000	0.000	0.000	0.000	0.008	1.09
Non-vectorized cubature::cuhre	50	0.002	0.002	0.002	0.002	0.002	0.004	0.081	11.90
Vectorized cubature::cuhre	50	0.001	0.001	0.001	0.001	0.001	0.001	0.050	7.38

Gaussian centered at \(\frac{1}{2}\)

testFn4 <- function(x) {
    a <- 0.1
    s <- sum((x - 0.5)^2)
    ((2 / sqrt(pi)) / (2. * a))^length(x) * exp (-s / (a * a))
}

testFn4_v <- function(x) {
    a <- 0.1
    r <- apply(x, 2, function(z) {
        s <- sum((z - 0.5)^2)
        ((2 / sqrt(pi)) / (2. * a))^length(z) * exp (-s / (a * a))
    })
    matrix(r, ncol = ncol(x))
}

d <- harness(f = testFn4, fv = testFn4_v,
             lowerLimit = rep(0, 2), upperLimit = rep(1, 2), times = 20)
knitr::kable(d, digits = 3)

expr	n.eval	min	lw.qu	median	mean	up.qu	max	total	relative
Non-vectorized Hcubature	20	0.003	0.003	0.003	0.003	0.004	0.005	0.070	1.19
Vectorized Hcubature	20	0.003	0.003	0.003	0.003	0.003	0.005	0.060	1.00
Non-vectorized Pcubature	20	0.005	0.005	0.005	0.005	0.005	0.007	0.106	1.74
Vectorized Pcubature	20	0.004	0.004	0.004	0.004	0.004	0.007	0.089	1.52
Non-vectorized cubature::cuhre	20	0.007	0.007	0.008	0.008	0.008	0.012	0.157	2.68
Vectorized cubature::cuhre	20	0.006	0.006	0.006	0.006	0.006	0.008	0.127	2.16

Double Gaussian

testFn5 <- function(x) {
    a <- 0.1
    s1 <- sum((x - 1 / 3)^2)
    s2 <- sum((x - 2 / 3)^2)
    0.5 * ((2 / sqrt(pi)) / (2. * a))^length(x) * (exp(-s1 / (a * a)) + exp(-s2 / (a * a)))
}
testFn5_v <- function(x) {
    a <- 0.1
    r <- apply(x, 2, function(z) {
        s1 <- sum((z - 1 / 3)^2)
        s2 <- sum((z - 2 / 3)^2)
        0.5 * ((2 / sqrt(pi)) / (2. * a))^length(z) * (exp(-s1 / (a * a)) + exp(-s2 / (a * a)))
    })
    matrix(r, ncol = ncol(x))
}

d <- harness(f = testFn5, fv = testFn5_v,
             lowerLimit = rep(0, 2), upperLimit = rep(1, 2), times = 20)
knitr::kable(d, digits = 3)

expr	n.eval	min	lw.qu	median	mean	up.qu	max	total	relative
Non-vectorized Hcubature	20	0.008	0.008	0.008	0.008	0.008	0.008	0.157	1.60
Vectorized Hcubature	20	0.007	0.007	0.007	0.007	0.007	0.009	0.143	1.41
Non-vectorized Pcubature	20	0.005	0.005	0.005	0.006	0.006	0.008	0.117	1.12
Vectorized Pcubature	20	0.005	0.005	0.005	0.005	0.005	0.005	0.099	1.00
Non-vectorized cubature::cuhre	20	0.015	0.015	0.015	0.015	0.015	0.018	0.303	3.02
Vectorized cubature::cuhre	20	0.012	0.012	0.013	0.013	0.013	0.015	0.256	2.56

Tsuda’s Example

testFn6 <- function(x) {
    a <- (1 + sqrt(10.0)) / 9.0
    prod( a / (a + 1) * ((a + 1) / (a + x))^2)
}

testFn6_v <- function(x) {
    a <- (1 + sqrt(10.0)) / 9.0
    r <- apply(x, 2, function(z) prod( a / (a + 1) * ((a + 1) / (a + z))^2))
    matrix(r, ncol = ncol(x))
}

d <- harness(f = testFn6, fv = testFn6_v,
             lowerLimit = rep(0, 3), upperLimit = rep(1, 3), times = 20)
knitr::kable(d, digits = 3)

expr	n.eval	min	lw.qu	median	mean	up.qu	max	total	relative
Non-vectorized Hcubature	20	0.004	0.004	0.004	0.006	0.004	0.050	0.128	1.21
Vectorized Hcubature	20	0.003	0.003	0.003	0.003	0.004	0.004	0.068	1.00
Non-vectorized Pcubature	20	0.019	0.020	0.020	0.021	0.021	0.023	0.411	6.13
Vectorized Pcubature	20	0.015	0.016	0.016	0.016	0.016	0.018	0.321	4.82
Non-vectorized cubature::cuhre	20	0.010	0.010	0.010	0.010	0.010	0.012	0.202	3.05
Vectorized cubature::cuhre	20	0.007	0.007	0.007	0.007	0.008	0.008	0.148	2.26

Morokoff & Calflish Example

testFn7 <- function(x) {
    n <- length(x)
    p <- 1/n
    (1 + p)^n * prod(x^p)
}
testFn7_v <- function(x) {
    matrix(apply(x, 2, function(z) {
        n <- length(z)
        p <- 1/n
        (1 + p)^n * prod(z^p)
    }), ncol = ncol(x))
}

d <- harness(f = testFn7, fv = testFn7_v,
             lowerLimit = rep(0, 3), upperLimit = rep(1, 3), times = 20)
knitr::kable(d, digits = 3)

expr	n.eval	min	lw.qu	median	mean	up.qu	max	total	relative
Non-vectorized Hcubature	20	0.008	0.008	0.008	0.009	0.009	0.013	0.181	1.30
Vectorized Hcubature	20	0.006	0.006	0.007	0.007	0.007	0.009	0.136	1.00
Non-vectorized Pcubature	20	0.020	0.021	0.021	0.021	0.022	0.024	0.426	3.24
Vectorized Pcubature	20	0.014	0.015	0.015	0.016	0.016	0.020	0.315	2.35
Non-vectorized cubature::cuhre	20	0.094	0.097	0.099	0.100	0.101	0.122	2.001	15.20
Vectorized cubature::cuhre	20	0.061	0.063	0.065	0.065	0.067	0.069	1.297	9.89

Wang-Landau Sampling 1d, 2d Examples

I.1d <- function(x) {
    sin(4 * x) *
        x * ((x * ( x * (x * x - 4) + 1) - 1))
}
I.1d_v <- function(x) {
    matrix(apply(x, 2, function(z)
        sin(4 * z) *
        z * ((z * ( z * (z * z - 4) + 1) - 1))),
        ncol = ncol(x))
}
d <- harness(f = I.1d, fv = I.1d_v,
             lowerLimit = -2, upperLimit = 2, times = 100)
knitr::kable(d, digits = 3)

expr	n.eval	min	lw.qu	median	mean	up.qu	max	total	relative
Non-vectorized Hcubature	100	0.000	0.000	0.000	0.000	0.000	0.002	0.039	2.50
Vectorized Hcubature	100	0.000	0.000	0.000	0.000	0.000	0.001	0.037	2.36
Non-vectorized Pcubature	100	0.000	0.000	0.000	0.000	0.000	0.000	0.015	1.00
Vectorized Pcubature	100	0.000	0.000	0.000	0.000	0.000	0.001	0.030	1.96
Non-vectorized cubature::cuhre	100	0.001	0.001	0.001	0.001	0.001	0.001	0.062	4.11
Vectorized cubature::cuhre	100	0.001	0.001	0.001	0.001	0.001	0.003	0.093	5.96

I.2d <- function(x) {
    x1 <- x[1]; x2 <- x[2]
    sin(4 * x1 + 1) * cos(4 * x2) * x1 * (x1 * (x1 * x1)^2 - x2 * (x2 * x2 - x1) +2)
}
I.2d_v <- function(x) {
    matrix(apply(x, 2,
                 function(z) {
                     x1 <- z[1]; x2 <- z[2]
                     sin(4 * x1 + 1) * cos(4 * x2) * x1 * (x1 * (x1 * x1)^2 - x2 * (x2 * x2 - x1) +2)
                 }),
           ncol = ncol(x))
}
d <- harness(f = I.2d, fv = I.2d_v,
             lowerLimit = rep(-1, 2), upperLimit = rep(1, 2), times = 100)
knitr::kable(d, digits = 3)

expr	n.eval	min	lw.qu	median	mean	up.qu	max	total	relative
Non-vectorized Hcubature	100	0.012	0.012	0.012	0.012	0.013	0.015	1.244	12.10
Vectorized Hcubature	100	0.008	0.008	0.008	0.008	0.008	0.011	0.830	8.07
Non-vectorized Pcubature	100	0.001	0.001	0.001	0.001	0.001	0.002	0.111	1.09
Vectorized Pcubature	100	0.001	0.001	0.001	0.001	0.001	0.003	0.105	1.00
Non-vectorized cubature::cuhre	100	0.003	0.003	0.003	0.003	0.003	0.005	0.311	3.00
Vectorized cubature::cuhre	100	0.002	0.002	0.002	0.002	0.002	0.005	0.222	2.09

Implementation Notes

About the only real modification we have made to the underlying cubature library is that we use M = 16 rather than the default M = 19 suggested by the original author for pcubature. This allows us to comply with CRAN package size limits and seems to work reasonably well for the above tests. Future versions will allow for such customization on demand.

The changes made to the Cuba library are managed in a Github repo branch: each time a new release is made, we update the main branch, and keep all changes for Unix platforms in a branch named R_pkg against the current main branch. Customization for windows is done in the package itself using the Makevars.win script.

Summary

The recommendations are:

1. Vectorize your function. The time spent in so doing pays back enormously. This is easy to do and the examples above show how.

2. Vectorized hcubature seems to be a good starting point.

3. For smooth integrands in low dimensions (\(\leq 3\)), pcubature might be worth trying out. Experiment before using in a production package.

Session Info

sessionInfo()

## R version 4.4.1 (2024-06-14)
## Platform: x86_64-apple-darwin20
## Running under: macOS Sonoma 14.5
## 
## Matrix products: default
## BLAS:   /Library/Frameworks/R.framework/Versions/4.4-x86_64/Resources/lib/libRblas.0.dylib 
## LAPACK: /Library/Frameworks/R.framework/Versions/4.4-x86_64/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.0
## 
## locale:
## [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
## 
## time zone: America/Los_Angeles
## tzcode source: internal
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] mvtnorm_1.2-5  cubature_2.1.1 benchr_0.2.5  
## 
## loaded via a namespace (and not attached):
##  [1] digest_0.6.36      R6_2.5.1           fastmap_1.2.0      xfun_0.45         
##  [5] cachem_1.1.0       knitr_1.48         htmltools_0.5.8.1  rmarkdown_2.27    
##  [9] lifecycle_1.0.4    cli_3.6.3          RcppProgress_0.4.2 sass_0.4.9        
## [13] jquerylib_0.1.4    compiler_4.4.1     tools_4.4.1        evaluate_0.24.0   
## [17] bslib_0.7.0        Rcpp_1.0.12        yaml_2.3.9         rlang_1.1.4       
## [21] jsonlite_1.8.8