Unified Cubature Integration Interface

Integrate a function within specified limits using method specified. Further arguments specific to method as well as other arguments to f may be passed. For defaults used in each method, see help on the method or default_args().

Usage

cubintegrate(
  f,
  lower,
  upper,
  fDim = 1,
  method = c("hcubature", "pcubature", "cuhre", "divonne", "suave", "vegas"),
  relTol = 1e-05,
  absTol = 1e-12,
  maxEval = 10^6,
  nVec = 1L,
  ...
)

Arguments

f

The function (integrand) to be integrated. Can be vectorized version, but the additional arguments ... must indicate via either vectorInterface = TRUE for hcubature and pcubature, or a value for nVec. See details on each method.

lower

The lower limit of integration, a vector for hypercubes.

upper

The upper limit of integration, a vector for hypercubes.

fDim

The number of components of f, default 1, bears no relation to the dimension of the hypercube over which integration is performed.

method

the method to use should be one of "hcubature", "pcubature", "cuhre", "divonne", "suave" or "vegas".

relTol

The maximum tolerance, default 1e-5.

absTol

the absolute tolerance, default 1e-12.

maxEval

The maximum number of function evaluations needed, default 10^6. Note that the actual number of function evaluations performed is only approximately guaranteed not to exceed this number.

nVec

the number of vectorization points for Cuba C library, default 1, but can be set to an integer > 1 for vectorization, for example, 1024. The function f above needs to handle the vector of points appropriately; see vignette examples. Unlike Cuba, the cubature C library manages the number of points on its own and can vary between calls. Therefore, any value for nVec greater than one implies vectorization for a cubature method.

...

All other arguments which may include integration method specific parameters and those for f. Unrecognized parameters for integration method are presumed to be intended for f and so processed.

Value

The returned value is a list of items:

integral

the value of the integral

error

the estimated absolute error

neval

the number of times the function was evaluated

returnCode

the actual integer return code of the C routine; a non-zero value usually indicates problems; further interpretation depends on method

nregions

forcCuba routines, the actual number of subregions needed

prob

the \(\chi^2\)-probability (not the \(\chi^2\)-value itself!) that error is not a reliable estimate of the true integration error.

See also

default_args(), hcubature(), pcubature(), cuhre(), vegas(), suave(), divonne()

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))
}
cubintegrate(f = I.1d, lower = -2, upper = 2, method = "pcubature")
#> $integral
#> [1] 1.635644
#> 
#> $error
#> [1] 1.332268e-15
#> 
#> $neval
#> [1] 65
#> 
#> $returnCode
#> [1] 0
#> 
cubintegrate(f = I.1d, lower = -2, upper = 2, method = "cuhre", flags=list(verbose = 2))
#> $integral
#> [1] 1.635644
#> 
#> $error
#> [1] 1.518009e-05
#> 
#> $nregions
#> [1] 12
#> 
#> $neval
#> [1] 253
#> 
#> $prob
#> [1] 0
#> 
#> $returnCode
#> [1] 0
#> 
cubintegrate(f = I.1d_v, lower = -2, upper = 2, method = "hcubature", nVec = 2L)
#> $integral
#> [1] 1.635644
#> 
#> $error
#> [1] 4.024021e-09
#> 
#> $neval
#> [1] 105
#> 
#> $returnCode
#> [1] 0
#> 
cubintegrate(f = I.1d_v, lower = -2, upper = 2, method = "cuhre", nVec = 128L)
#> $integral
#> [1] 1.635644
#> 
#> $error
#> [1] 1.518009e-05
#> 
#> $nregions
#> [1] 12
#> 
#> $neval
#> [1] 253
#> 
#> $prob
#> [1] 0
#> 
#> $returnCode
#> [1] 0
#>