Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English version of the page.

# integral3

Numerically evaluate triple integral

## Syntax

``q = integral3(fun,xmin,xmax,ymin,ymax,zmin,zmax)``
``q = integral3(fun,xmin,xmax,ymin,ymax,zmin,zmax,Name,Value)``

## Description

example

````q = integral3(fun,xmin,xmax,ymin,ymax,zmin,zmax)` approximates the integral of the function `z = fun(x,y,z)` over the region `xmin` ≤ `x` ≤ `xmax`, `ymin(x)` ≤ `y` ≤ `ymax(x)` and `zmin(x,y)` ≤ `z` ≤ `zmax(x,y)`.```

example

````q = integral3(fun,xmin,xmax,ymin,ymax,zmin,zmax,Name,Value)` specifies additional options with one or more `Name,Value` pair arguments.```

## Examples

collapse all

Define the anonymous function $f\left(x,y,z\right)=y\mathrm{sin}x+z\mathrm{cos}x$.

`fun = @(x,y,z) y.*sin(x)+z.*cos(x)`
```fun = function_handle with value: @(x,y,z)y.*sin(x)+z.*cos(x) ```

Integrate over the region $0\le x\le \pi$, $0\le y\le 1$, and $-1\le z\le 1$.

`q = integral3(fun,0,pi,0,1,-1,1)`
```q = 2.0000 ```

Define the anonymous function $f\left(x,y,z\right)=x\mathrm{cos}y+{x}^{2}\mathrm{cos}z$.

`fun = @(x,y,z) x.*cos(y) + x.^2.*cos(z)`
```fun = function_handle with value: @(x,y,z)x.*cos(y)+x.^2.*cos(z) ```

Define the limits of integration.

```xmin = -1; xmax = 1; ymin = @(x)-sqrt(1 - x.^2); ymax = @(x) sqrt(1 - x.^2); zmin = @(x,y)-sqrt(1 - x.^2 - y.^2); zmax = @(x,y) sqrt(1 - x.^2 - y.^2);```

Evaluate the definite integral with the `'tiled'` method.

`q = integral3(fun,xmin,xmax,ymin,ymax,zmin,zmax,'Method','tiled')`
```q = 0.7796 ```

Define the anonymous parameterized function $f\left(x,y,z\right)=10/\left({x}^{2}+{y}^{2}+{z}^{2}+a\right)$.

```a = 2; f = @(x,y,z) 10./(x.^2 + y.^2 + z.^2 + a);```

Evaluate the triple integral over the region $-\infty \le x\le 0$, $-100\le y\le 0$, and $-100\le z\le 0$.

```format long q1 = integral3(f,-Inf,0,-100,0,-100,0)```
```q1 = 2.734244598320928e+03 ```

Evaluate the integral again and specify accuracy to approximately 9 significant digits.

`q2 = integral3(f,-Inf,0,-100,0,-100,0,'AbsTol', 0,'RelTol',1e-9)`
```q2 = 2.734244599944285e+03 ```

Use nested calls to `integral3` and `integral` to calculate the volume of a 4-D sphere.

The volume of a 4-D sphere of radius $\mathit{r}$ is

`${\mathit{V}}_{4}\left(\mathit{r}\right)={\int }_{0}^{2\pi }{\int }_{0}^{\pi }{\int }_{0}^{\pi }{\int }_{0}^{\mathit{r}}{\mathit{r}}^{3}\text{\hspace{0.17em}}{\mathrm{sin}}^{2}\left(\theta \right)\text{\hspace{0.17em}}\mathrm{sin}\left(\varphi \right)\text{\hspace{0.17em}}\mathit{dr}\text{\hspace{0.17em}}\mathit{d}\theta \text{\hspace{0.17em}}\mathit{d}\varphi \text{\hspace{0.17em}}\mathit{d}\xi .$`

The `integral` quadrature functions in MATLAB® directly support 1-D, 2-D, and 3-D integrations. However, to solve 4-D and higher order integrals, you need to nest calls to the solvers.

Create a function handle $\mathit{f}\left(\mathit{r},\theta ,\varphi ,\xi \right)$ for the integrand using element-wise operators (`.^` and `.*`).

`f = @(r,theta,phi,xi) r.^3 .* sin(theta).^2 .* sin(phi);`

Next, create a function handle that calculates three of the integrals using `integral3`.

`Q = @(r) integral3(@(theta,phi,xi) f(r,theta,phi,xi),0,pi,0,pi,0,2*pi);`

Finally, use `Q` as the integrand in a call to `integral`. Solving this integral requires choosing a value for the radius $\mathit{r}$, so use $\mathit{r}=2$.

`I = integral(Q,0,2,'ArrayValued',true)`
```I = 78.9568 ```

The exact answer is $\frac{{\pi }^{2}{\mathit{r}}^{4}}{2\text{\hspace{0.17em}}\Gamma \left(2\right)}$.

`I_exact = pi^2*2^4/(2*gamma(2))`
```I_exact = 78.9568 ```

## Input Arguments

collapse all

Integrand, specified as a function handle, defines the function to be integrated over the region `xmin` ≤ `x` ≤ `xmax`, `ymin`(`x`) ≤ `y` ≤ `ymax`(`x`), and `zmin`(`x,y`) ≤ `z` ≤ `zmax`(`x,y`). The function `fun` must accept three arrays of the same size and return an array of corresponding values. It must perform element-wise operations.

Data Types: `function_handle`

Lower limit of x, specified as a real scalar value that is either finite or infinite.

Data Types: `double` | `single`

Upper limit of x, specified as a real scalar value that is either finite or infinite.

Data Types: `double` | `single`

Lower limit of y, specified as a real scalar value that is either finite or infinite. You also can specify `ymin` to be a function handle (a function of x) when integrating over a nonrectangular region.

Data Types: `double` | `function_handle` | `single`

Upper limit of y, specified as a real scalar value that is either finite or infinite. You also can specify `ymax` to be a function handle (a function of x) when integrating over a nonrectangular region.

Data Types: `double` | `function_handle` | `single`

Lower limit of z, specified as a real scalar value that is either finite or infinite. You also can specify `zmin` to be a function handle (a function of x,y) when integrating over a nonrectangular region.

Data Types: `double` | `function_handle` | `single`

Upper limit of z, specified as a real scalar value that is either finite or infinite. You also can specify `zmax` to be a function handle (a function of x,y) when integrating over a nonrectangular region.

Data Types: `double` | `function_handle` | `single`

### Name-Value Pair Arguments

Specify optional comma-separated pairs of `Name,Value` arguments. `Name` is the argument name and `Value` is the corresponding value. `Name` must appear inside quotes. You can specify several name and value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

Example: `'AbsTol',1e-12` sets the absolute error tolerance to approximately 12 decimal places of accuracy.

Absolute error tolerance, specified as the comma-separated pair consisting of `'AbsTol'` and a nonnegative real number. `integral3` uses the absolute error tolerance to limit an estimate of the absolute error, |qQ|, where q is the computed value of the integral and Q is the (unknown) exact value. `integral3` might provide more decimal places of precision if you decrease the absolute error tolerance. The default value is `1e-10`.

### Note

`AbsTol` and `RelTol` work together. `integral3` might satisfy the absolute error tolerance or the relative error tolerance, but not necessarily both. For more information on using these tolerances, see the Tips section.

Example: `'AbsTol',1e-12` sets the absolute error tolerance to approximately 12 decimal places of accuracy.

Data Types: `double` | `single`

Relative error tolerance, specified as the comma-separated pair consisting of `'RelTol'` and a nonnegative real number. `integral3` uses the relative error tolerance to limit an estimate of the relative error, |qQ|/|Q|, where q is the computed value of the integral and Q is the (unknown) exact value. `integral3` might provide more significant digits of precision if you decrease the relative error tolerance. The default value is `1e-6`.

### Note

`RelTol` and `AbsTol` work together. `integral3` might satisfy the relative error tolerance or the absolute error tolerance, but not necessarily both. For more information on using these tolerances, see the Tips section.

Example: `'RelTol',1e-9` sets the relative error tolerance to approximately 9 significant digits.

Data Types: `double` | `single`

Integration method, specified as the comma-separated pair consisting of `'Method'` and one of the methods described below.

Integration MethodDescription
`'auto'`For most cases, `integral3` uses the `'tiled'` method. It uses the `'iterated'` method when any of the integration limits are infinite. This is the default method.
`'tiled'``integral3` calls `integral` to integrate over `xmin` ≤ `x` ≤ `xmax`. It calls `integral2` with the `'tiled'` method to evaluate the double integral over `ymin(x)` ≤ `y` ≤ `ymax(x)` and `zmin(x,y)` ≤ `z` ≤ `zmax(x,y)`.
`'iterated'``integral3` calls `integral` to integrate over `xmin` ≤ `x` ≤ `xmax`. It calls `integral2` with the `'iterated'` method to evaluate the double integral over `ymin(x)` ≤ `y` ≤ `ymax(x)` and `zmin(x,y)` ≤ `z` ≤ `zmax(x,y)`. The integration limits can be infinite.

Example: `'Method','tiled'` specifies the tiled integration method.

Data Types: `char` | `string`

## Tips

• The `integral3` function attempts to satisfy:

`abs(q - Q) <= max(AbsTol,RelTol*abs(q))`
where `q` is the computed value of the integral and `Q` is the (unknown) exact value. The absolute and relative tolerances provide a way of trading off accuracy and computation time. Usually, the relative tolerance determines the accuracy of the integration. However if `abs(q)` is sufficiently small, the absolute tolerance determines the accuracy of the integration. You should generally specify both absolute and relative tolerances together.

• The `'iterated'` method can be more effective when your function has discontinuities within the integration region. However, the best performance and accuracy occurs when you split the integral at the points of discontinuity and sum the results of multiple integrations.

• When integrating over nonrectangular regions, the best performance and accuracy occurs when any or all of the limits: `ymin`, `ymax`, `zmin`, `zmax` are function handles. Avoid setting integrand function values to zero to integrate over a nonrectangular region. If you must do this, specify `'iterated'` method.

• Use the `'iterated'` method when any or all of the limits: `ymin(x)`, `ymax(x)`, `zmin(x,y)`, `zmax(x,y)` are unbounded functions.

• When paramaterizing anonymous functions, be aware that parameter values persist for the life of the function handle. For example, the function `fun = @(x,y,z) x + y + z + a` uses the value of `a` at the time `fun` was created. If you later decide to change the value of `a`, you must redefine the anonymous function with the new value.

• If you are specifying single-precision limits of integration, or if `fun` returns single-precision results, you may need to specify larger absolute and relative error tolerances.

• To solve 4-D and higher order integrals, you can nest calls to `integral`, `integral2`, and `integral3`. Another option is to use the `integralN` function on the MATLAB® File Exchange, which solves integrals of orders 4 - 6.

## References

[1] L.F. Shampine “Vectorized Adaptive Quadrature in MATLAB,” Journal of Computational and Applied Mathematics, 211, 2008, pp.131–140.

[2] L.F. Shampine, "MATLAB Program for Quadrature in 2D." Applied Mathematics and Computation. Vol. 202, Issue 1, 2008, pp. 266–274.