integral

Numerical integration

Syntax

q = integral(fun,xmin,xmax)

q = integral(fun,xmin,xmax,Name=Value)

Description

q = integral(fun,xmin,xmax) numerically integrates function fun from xmin to xmax using global adaptive quadrature and default error tolerances.

q = integral(fun,xmin,xmax,Name=Value) specifies options using one or more name-value arguments. For example, specify the WayPoints name-value argument as a vector of real or complex numbers to indicate specific points for the integrator to use.

Examples

Improper Integral

Create the function $$f(x)=e^{-x^2}(\ln x{)}^2$$.

fun = @(x) exp(-x.^2).*log(x).^2;

Evaluate the integral from x=0 to x=Inf.

q = integral(fun,0,Inf)

q = 
1.9475

Parameterized Function

Create the function $$f(x)=1/(x^3-2x-c)$$ with one parameter, $$c$$.

fun = @(x,c) 1./(x.^3-2*x-c);

Evaluate the integral from x=0 to x=2 at c=5.

q = integral(@(x) fun(x,5),0,2)

q = 
-0.4605

For more information on this technique, see Parameterizing Functions.

Singularity at Lower Limit

Create the function $$f(x)=\ln (x)$$.

fun = @(x) log(x);

Evaluate the integral from x=0 to x=1 with the default error tolerances.

format long
q1 = integral(fun,0,1)

q1 = 
  -1.000000010959678

Then evaluate the integral with 12 decimal places of accuracy. Set RelTol to 0 so that integral only attempts to satisfy the absolute error tolerance.

q2 = integral(fun,0,1,AbsTol=1e-12,RelTol=0)

q2 = 
  -1.000000000000010

Complex Contour Integration Using Waypoints

Create the function $$f(z)=1/(2z-1)$$.

fun = @(z) 1./(2*z-1);

Integrate in the complex plane over the triangular path from 0 to 1+1i to 1-1i to 0 by specifying waypoints.

q = integral(fun,0,0,Waypoints=[1+1i,1-1i])

q = 
0.0000 - 3.1416i

Vector-Valued Function

Create the vector-valued function $$f(x)=[\sin x,\sin 2x,\sin 3x,\sin 4x,\sin 5x]$$ and integrate from x=0 to x=1. Specify the ArrayValued name-value argument as true to evaluate the integral of an array-valued or vector-valued function.

fun = @(x) sin((1:5)*x);
q = integral(fun,0,1,ArrayValued=true)

q = 1×5

    0.4597    0.7081    0.6633    0.4134    0.1433

Integral of Function with Scalar Input

Since R2026a

Create the function $f\left(x\right)=2x-x^2$ assuming scalar input.

fun = @(x) 2*x-x^2;

Evaluate the integral from $x=0$ to $x=1$. Specify the Vectorized name-value argument as false to compute the integral without using vectorization.

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

q = 
0.6667

Improper Integral of Oscillatory Function

Create the function $$f(x)=x^5{e}^{-x}\sin x$$.

fun = @(x) x.^5.*exp(-x).*sin(x);

Evaluate the integral from x=0 to x=Inf, adjusting the absolute and relative tolerances.

format long
q = integral(fun,0,Inf,AbsTol=1e-13,RelTol=1e-8)

q = 
 -14.999999999998360

Input Arguments

fun — Integrand

function handle

Integrand, specified as a function handle that defines the function to be integrated.

For scalar-valued problems, the function y = fun(x) must accept a vector argument x and return a vector result y. So, fun generally uses array operators instead of matrix operators. For example, use .* (times) rather than * (mtimes).

If you specify the ArrayValued name-value argument as true, then fun must accept a scalar input and return an array of fixed size.

xmin — Lower limit of x

real number | complex number

Lower limit of x, specified as a real number (finite or infinite) or a complex number (finite). If either xmin or xmax is complex, then integral approximates the path integral along the straight line from xmin to xmax.

Data Types: double | single
Complex Number Support: Yes

xmax — Upper limit of x

real number | complex number

Upper limit of x, specified as a real number (finite or infinite) or a complex number (finite). If either xmin or xmax is complex, then integral approximates the path integral along the straight line from xmin to xmax.

Data Types: double | single
Complex Number Support: Yes

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 = integral(fun,xmin,xmax,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. integral 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. integral might provide more decimal places of precision if you decrease the absolute error tolerance.

Note

AbsTol and RelTol work together. integral 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 = integral(fun,xmin,xmax,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. integral 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. integral might provide more significant digits of precision if you decrease the relative error tolerance.

Note

RelTol and AbsTol work together. integral 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 = integral(fun,xmin,xmax,RelTol=1e-9)

Data Types: double | single

ArrayValued — Function is array-valued

false or 0 (default) | true or 1

Function is array-valued, specified as a numeric or logical 1 (true) or 0 (false). Specify ArrayValued as true or 1 to indicate that fun is a function that accepts a scalar input and returns a vector, matrix, or N-D array output.

The default value of false indicates that fun is a function that accepts a vector input and returns a vector output.

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. For scalar-valued functions, the integrand function y = fun(x) must accept a vector argument x and operates element-wise, returning a vector result y.

If you specify Vectorized as false, then the integrand function accepts only a scalar argument x and returns a scalar result y.

Note

If you specify ArrayValued as true, then integral ignores the value of Vectorized.

Waypoints — Integration waypoints

vector of real or complex numbers

Integration waypoints, specified as a vector of real or complex numbers. Use waypoints to indicate points in the integration interval that you want the integrator to use in the initial mesh:

• Add more evaluation points near interesting features of the function, such as a local extremum.

• Integrate efficiently across discontinuities of the integrand by specifying the locations of the discontinuities.

• Perform complex contour integrations by specifying complex numbers as waypoints. If xmin, xmax, or any entry of the waypoints vector is complex, then the integration is performed over a sequence of straight line paths in the complex plane. In this case, all of the integration limits and waypoints must be finite.

Do not use waypoints to specify singularities. Instead, split the interval and add the results of separate integrations with the singularities at the endpoints.

Example: q = integral(fun,xmin,xmax,Waypoints=[1+1i,1-1i]) specifies two complex waypoints along the interval of integration.

Data Types: double | single
Complex Number Support: Yes

Output Arguments

q — Computed value of integral

numeric scalar | numeric array

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

Tips

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

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

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.

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.

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

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