integral {calculus}

Numerical Integration

Description

Computes the integrals of functions or characters in arbitrary orthogonal coordinate systems.

Usage

integral(
  f,
  bounds,
  params = list(),
  coordinates = "cartesian",
  relTol = 0.001,
  absTol = 1e-12,
  method = NULL,
  vectorize = NULL,
  drop = TRUE,
  verbose = FALSE,
  ...
)

Arguments

f

array of characters or a function returning a numeric array.

bounds

list containing the lower and upper bounds for each variable. If the two bounds coincide, or if a single number is specified, the corresponding variable is not integrated and its value is fixed.

params

list of additional parameters passed to f.

coordinates

coordinate system to use. One of: cartesian, polar, spherical, cylindrical, parabolic, parabolic-cylindrical or a character vector of scale factors for each variable.

relTol

the maximum relative tolerance.

absTol

the absolute tolerance.

method

the method to use. One of "mc", "hcubature", "pcubature", "cuhre", "divonne", "suave" or "vegas". Methods other than "mc" (naive Monte Carlo) require the cubature package to be installed (efficient integration in C). The defaul uses "hcubature" if cubature is installed or "mc" otherwise.

vectorize

logical. Use vectorization? If TRUE, it can significantly boost performance but f needs to handle the vector of inputs appropriately. The default uses FALSE if f is a function, TRUE otherwise.

drop

if TRUE, return the integral as a vector and not as an array for vector-valued functions.

verbose

logical. Print on progress?

...

additional arguments passed to cubintegrate, when method "hcubature", "pcubature", "cuhre", "divonne", "suave" or "vegas" is used.

Details

The function integrates seamlessly with cubature for efficient numerical integration in C. If the package cubature is not installed, the function implements a naive Monte Carlo integration by default. For arbitrary orthogonal coordinates q_1\dots q_n the integral is computed as:

\int J\cdot f(q_1\dots q_n) dq_1\dots dq_n

where J=\prod_i h_i is the Jacobian determinant of the transformation and is equal to the product of the scale factors h_1\dots h_n.

Value

list with components

value

the final estimate of the integral.

error

estimate of the modulus of the absolute error.

cuba

cubature output when method "hcubature", "pcubature", "cuhre", "divonne", "suave" or "vegas" is used.

References

Guidotti E (2022). "calculus: High-Dimensional Numerical and Symbolic Calculus in R." Journal of Statistical Software, 104(5), 1-37. doi:10.18637/jss.v104.i05

See Also

Other integrals: ode()

Examples

### unidimensional integral
i <- integral("sin(x)", bounds = list(x = c(0,pi)))
i$value

### multidimensional integral
f <- function(x,y) x*y
i <- integral(f, bounds = list(x = c(0,1), y = c(0,1)))
i$value

### vector-valued integrals
f <- function(x,y) c(x, y, x*y)
i <- integral(f, bounds = list(x = c(0,1), y = c(0,1)))
i$value

### tensor-valued integrals
f <- function(x,y) array(c(x^2, x*y, x*y, y^2), dim = c(2,2))
i <- integral(f, bounds = list(x = c(0,1), y = c(0,1)))
i$value

### area of a circle
i <- integral(1, 
              bounds = list(r = c(0,1), theta = c(0,2*pi)), 
              coordinates = "polar")
i$value

### surface of a sphere
i <- integral(1, 
              bounds = list(r = 1, theta = c(0,pi), phi = c(0,2*pi)), 
              coordinates = "spherical")
i$value

### volume of a sphere
i <- integral(1, 
         bounds = list(r = c(0,1), theta = c(0,pi), phi = c(0,2*pi)), 
         coordinates = "spherical")
i$value