R: Unified Cubature Integration Interface

cubintegrate {cubature} | R Documentation

## Unified Cubature Integration Interface

### Description

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`'s.

### 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 relative error for cubature; for Cuba it is 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` | for Cuba routines, the actual number of subregions needed
`prob` | the Chi2-probability (not the Chi2-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")
    cubintegrate(f = I.1d, lower = -2, upper = 2, method = "cuhre", flags=list(verbose = 2))
    cubintegrate(f = I.1d_v, lower = -2, upper = 2, method = "hcubature", nVec = 2L)
    cubintegrate(f = I.1d_v, lower = -2, upper = 2, method = "cuhre", nVec = 128L)

[Package cubature version 2.0.4.2 Index]