integral2

Numerically evaluate double integral

Syntax

q = integral2(fun,xmin,xmax,ymin,ymax)

q = integral2(fun,xmin,xmax,ymin,ymax,Name,Value)

Description

q = integral2(fun,xmin,xmax,ymin,ymax) approximates the integral of the function z = fun(x,y) over the planar region xmin ≤ x ≤ xmax and ymin(x) ≤ y ≤ ymax(x).

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

Examples

Integrate Triangular Region with Singularity at the Boundary

Consider the function

$$f(x,y)=\frac{1}{\left(\sqrt{x+y}\right){(1+x+y)}^2}$$.

This function is undefined when $$x$$ and $$y$$ are zero. integral2 performs best when singularities are on the integration boundary.

Create the anonymous function.

fun = @(x,y) 1./( sqrt(x + y) .* (1 + x + y).^2 )

fun = function_handle with value:
    @(x,y)1./(sqrt(x+y).*(1+x+y).^2)

Integrate over the triangular region bounded by $$0\le x\le 1$$ and $$0\le y\le 1-x$$.

ymax = @(x) 1 - x;
q = integral2(fun,0,1,0,ymax)

q = 
0.2854

Evaluate Double Integral in Polar Coordinates

Define the function

$$f(\theta ,r)=\frac{r}{\sqrt{r\cos \theta +r\sin \theta }{(1+r\cos \theta +r\sin \theta )}^2}$$

fun = @(x,y) 1./( sqrt(x + y) .* (1 + x + y).^2 );
polarfun = @(theta,r) fun(r.*cos(theta),r.*sin(theta)).*r;

Define a function for the upper limit of $$r$$.

rmax = @(theta) 1./(sin(theta) + cos(theta));

Integrate over the region bounded by $$0\le \theta \le \pi /2$$ and $$0\le r\le r_{max}$$.

q = integral2(polarfun,0,pi/2,0,rmax)

q = 
0.2854

Evaluate Double Integral of Parameterized Function with Specific Method and Error Tolerance

Create the anonymous parameterized function $$f(x,y)=a{x}^2+b{y}^2$$ with parameters $$a=3$$ and $$b=5$$.

a = 3; 
b = 5;
fun = @(x,y) a*x.^2 + b*y.^2;

Evaluate the integral over the region $$0\le x\le 5$$ and $$-5\le y\le 0$$. Specify the 'iterated' method and approximately 10 significant digits of accuracy.

format long
q = integral2(fun,0,5,-5,0,'Method','iterated',...
'AbsTol',0,'RelTol',1e-10)

q = 
     1.666666666666667e+03

Input Arguments

fun — Integrand

function handle

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

Data Types: function_handle

xmin — Lower limit of x

real number

Lower limit of x, specified as a real scalar value 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 scalar value 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 scalar value that is either finite or infinite. You can specify ymin to be a function handle (a function of x) when integrating over a nonrectangular region.

Data Types: double | function_handle | single

ymax — Upper limit of y

real number | function handle

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

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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

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

AbsTol — Absolute error tolerance

nonnegative real number

Absolute error tolerance, specified as the comma-separated pair consisting of 'AbsTol' and a nonnegative real number. integral2 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. integral2 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. integral2 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

RelTol — Relative error tolerance

nonnegative real number

Relative error tolerance, specified as the comma-separated pair consisting of 'RelTol' and a nonnegative real number. integral2 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. integral2 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. integral2 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

Method — Integration method

'auto' (default) | 'tiled' | 'iterated'

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

Integration Method	Description
'auto'	For most cases, integral2 uses the 'tiled' method. It uses the 'iterated' method when any of the integration limits are infinite. This is the default method.
'tiled'	integral2 transforms the region of integration to a rectangular shape and subdivides it into smaller rectangular regions as needed. The integration limits must be finite.
'iterated'	integral2 calls integral to perform an iterated integral. The outer integral is evaluated over xmin ≤ x ≤ xmax. The inner integral is evaluated over ymin(x) ≤ y ≤ ymax(x). The integration limits can be infinite.

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

Data Types: char | string

Tips

• The integral2 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 ymin, ymax, (or both) 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 ymin, ymax, (or both) are unbounded functions.

• When parameterizing anonymous functions, be aware that parameter values persist for the life of the function handle. For example, the function fun = @(x,y) x + y + 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 might need to specify larger absolute and relative error tolerances.

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.

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• Variable-sizing must be enable when method is auto or iterated.

• Function handles that return sparse matrix output are not supported.

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

Thread-Based Environment

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

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

Version History

Introduced in R2012a