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

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

q = integral3(fun,xmin,xmax,ymin,ymax,zmin,zmax,Name=Value) specifies options using one or more name-value arguments. For example, you can specify the absolute and relative error tolerances and the integration method.

Examples

Triple Integral with Finite Limits

Create the function $$f(x,y,z)=y\sin x+z\cos x$$.

fun = @(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

Triple Integral over Unit Sphere in Cartesian Coordinates

Create the function $$f(x,y,z)=x\cos y+x^2\cos z$$.

fun = @(x,y,z) x.*cos(y)+x.^2.*cos(z);

Specify the limits of integration as a unit sphere in Cartesian coordinates.

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 integral over the unit sphere using the "tiled" method.

q = integral3(fun,xmin,xmax,ymin,ymax,zmin,zmax,Method="tiled")

q = 
0.7796

Improper Triple Integral of Parameterized Function

Create the parameterized function $$f(x,y,z)=10/(x^2+y^2+z^2+a)$$ with a parameter $a=2$.

a = 2;
fun = @(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(fun,-Inf,0,-100,0,-100,0)

q1 = 
     2.734244598320928e+03

Evaluate the integral again, specifying an accuracy of approximately 9 significant digits.

q2 = integral3(fun,-Inf,0,-100,0,-100,0,AbsTol=0,RelTol=1e-9)

q2 = 
     2.734244599944285e+03

For more information on this technique, see Parameterizing Functions.

Triple Integral of Function with Scalar Inputs

Since R2026a

Create the function $f\left(x,y,z\right)=x^{4}y-y^3{z}^2$ assuming scalar inputs.

fun = @(x,y,z) x^4*y-y^3*z^2;

Integrate over the region bounded by $0\le x\le 1$, $0\le y\le 1$, and $0\le z\le 1$. Specify the Vectorized name-value argument as false to compute the triple integral without using vectorization.

q = integral3(fun,0,1,0,1,0,1,Vectorized=false)

q = 
0.0167

4-D Integral of Sphere

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 functions.

Calculate the volume of a 4-D sphere by using nested calls to integral3 and integral.

The volume of a 4-D sphere of radius $r$ is

$$V_4\left(r\right)={\int }_0^{2\pi }{\int }_0^{\pi }{\int }_0^{\pi }{\int }_0^r{r}^3{\sin }^2\left(\theta \right)\sin \left(\varphi \right)\text{dr}d\theta d\varphi d\xi .$$

Create a function $f\left(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 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 $r$, so use $r=2$.

I = integral(Q,0,2,ArrayValued=true)

I = 
78.9568

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

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

I_exact = 
78.9568

Input Arguments

fun — Integrand

function handle

Integrand, specified as a function handle that defines the function to be integrated. The function w = fun(x,y,z) must accept three arrays of the same size and return an array of corresponding values. The function must perform element-wise operations.

xmin — Lower limit of x

real number

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

Data Types: double | single

xmax — Upper limit of x

real number

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

Data Types: double | single

ymin — Lower limit of y

real number | function handle

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

Data Types: double | single | function_handle

ymax — Upper limit of y

real number | function handle

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

Data Types: double | single | function_handle

zmin — Lower limit of z

real number | function handle

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

Data Types: double | single | function_handle

zmax — Upper limit of z

real number | function handle

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

Data Types: double | single | function_handle

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: q = integral3(fun,xmin,xmax,ymin,ymax,zmin,zmax,AbsTol=1e-12) sets the absolute error tolerance to approximately 12 decimal places of accuracy.

AbsTol — Absolute error tolerance

1e-10 (default) | nonnegative real number

Absolute error tolerance, specified as a nonnegative real number. integral3 uses the absolute error tolerance to limit an estimate of the absolute error, |q – Q|, 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.

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: q = integral3(fun,xmin,xmax,ymin,ymax,zmin,zmax,AbsTol=1e-12)

Data Types: double | single

RelTol — Relative error tolerance

1e-6 (default) | nonnegative real number

Relative error tolerance, specified as a nonnegative real number. integral3 uses the relative error tolerance to limit an estimate of the relative error, |q – Q|/|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.

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: q = integral3(fun,xmin,xmax,ymin,ymax,zmin,zmax,RelTol=1e-9)

Data Types: double | single

Method — Integration method

"auto" (default) | "tiled" | "iterated"

Integration method, specified as one of the values in this table.

Integration Method	Description
"auto"	integral3 chooses whether to use the "tiled" or "iterated" method. For most cases, integral3 uses the "tiled" method. integral3 uses the "iterated" method when any of the integration limits are infinite.
"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). The integration limits must be finite.
"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.

Vectorized — Perform vectorized computation

true or 1 (default) | false or 0

Since R2026a

Perform vectorized computation, specified as a numeric or logical 1 (true) or 0 (false). By default, Vectorized is true and the computation of the integral is vectorized to run faster. The integrand function fun must accept three arrays of the same size and operates element-wise, returning an array of corresponding values. If the lower or upper limit of y is a function handle, ymin or ymax must accept a vector argument and return a vector of corresponding values. If the lower or upper limit of z is a function handle, zmin or zmax must accept two vector arguments of the same size and return a vector of corresponding values.

If you specify Vectorized as false, then fun, ymin, ymax, zmin, and zmax accept only scalar arguments and return scalar values.

Output Arguments

q — Computed value of triple integral

numeric scalar | numeric array

Computed value of the triple integral, returned as a numeric scalar or array.

Tips

• The integral3 function attempts to satisfy the following expression, where q is the computed value of the integral and Q is the (unknown) exact value.

  abs(q - Q) <= max(AbsTol,RelTol*abs(q))

  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. It is a best practice to 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 you integrate over nonrectangular regions, the best performance and accuracy occurs when any or all of the limits ymin, ymax, zmin, or zmax are function handles. Avoid setting integrand function values to zero to integrate over a nonrectangular region. If you must do so, specify the "iterated" method.

• Use the "iterated" method when any or all of the limits ymin, ymax, zmin, or zmax are unbounded functions.

• When you parameterize anonymous functions, 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 specify single-precision limits of integration, or if fun returns single-precision results, you might 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 MATLAB^® File Exchange, which solves integrals of orders 4 to 6.

References

[1] Shampine, L.F. “Vectorized Adaptive Quadrature in MATLAB.” Journal of Computational and Applied Mathematics 211, no. 2 (February 2008): 131–40. https://doi.org/10.1016/j.cam.2006.11.021.

[2] Shampine, L.F. "MATLAB Program for Quadrature in 2D." Applied Mathematics and Computation 202, no. 1 (August 2008): 266–74. https://doi.org/10.1016/j.amc.2008.02.012.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• You must enable support for variable-size arrays when the integration method is "auto" or "iterated".

• This function does not support function handles that return sparse matrix output.

• Generated code issues a warning if the size of the internal storage arrays is not large enough. If a warning occurs, as a workaround, you can try to divide the region of integration into pieces and sum the integrals over each piece.

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Refer to the usage notes and limitations in the C/C++ Code Generation section. The same usage notes and limitations apply to GPU code generation.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

The integral3 function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2012a

R2026a: Integrate functions with scalar inputs

You can integrate functions written for scalar inputs by specifying the Vectorized name-value argument as false.