gradient

Numerical gradient

Syntax

FX = gradient(F)

[FX,FY] = gradient(F)

[FX,FY,FZ,...,FN] = gradient(F)

[___] = gradient(F,h)

[___] = gradient(F,hx,hy,...,hN)

Description

FX = gradient(F) returns the one-dimensional numerical gradient of vector F. The output FX corresponds to ∂F/∂x, which are the differences in the x (horizontal) direction. The spacing between points is assumed to be 1.

[FX,FY] = gradient(F) returns the x and y components of the two-dimensional numerical gradient of matrix F. The additional output FY corresponds to ∂F/∂y, which are the differences in the y (vertical) direction. The spacing between points in each direction is assumed to be 1.

[FX,FY,FZ,...,FN] = gradient(F) returns the N components of the numerical gradient of F, where F is an array with N dimensions.

[___] = gradient(F,h) uses h as a uniform spacing between points in each direction. You can specify any of the output arguments in previous syntaxes.

[___] = gradient(F,hx,hy,...,hN) specifies N spacing parameters for the spacing in each dimension of F.

Examples

Gradient of Vector

Calculate the gradient of a monotonically increasing vector.

x = 1:10

x = 1×10

     1     2     3     4     5     6     7     8     9    10

fx = gradient(x)

fx = 1×10

     1     1     1     1     1     1     1     1     1     1

Contour Plot of Vector Field

Calculate the 2-D gradient of $$x{e}^{-x^2-y^2}$$ on a grid.

x = -2:0.2:2;
y = x';
z = x .* exp(-x.^2 - y.^2);
[px,py] = gradient(z);

Plot the contour lines and vectors in the same figure.

figure
contour(x,y,z)
hold on
quiver(x,y,px,py)
hold off

Linear Function Approximation

Use the gradient at a particular point to linearly approximate the function value at a nearby point and compare it to the actual value.

The equation for linear approximation of a function value is

$$f(x)\approx f(x_0)+{(\nabla f)}_{x_0}\cdot (x-x_0).$$

That is, if you know the value of a function $$f(x_0)$$ and the slope of the derivative $${(\nabla f)}_{x_0}$$ at a particular point $$x_0$$, then you can use this information to approximate the value of the function at a nearby point $$f(x)=f(x_0+ϵ)$$.

Calculate some values of the sine function between -1 and 0.5. Then calculate the gradient.

y = sin(-1:0.25:0.5);
yp = gradient(y,0.25);

Use the function value and derivative at x = 0.5 to predict the value of sin(0.5005).

y_guess = y(end) + yp(end)*(0.5005 - 0.5)

y_guess = 
0.4799

Compute the actual value for comparison.

y_actual = sin(0.5005)

y_actual = 
0.4799

Compute Gradient at Specified Point

Find the value of the gradient of a multivariate function at a specified point.

Consider the multivariate function $$f(x,y)=x^2{y}^3$$.

x = -3:0.2:3;
y = x';
f = x.^2 .* y.^3;
surf(x,y,f)
xlabel('x')
ylabel('y')
zlabel('z')

Calculate the gradient on the grid.

[fx,fy] = gradient(f,0.2);

Extract the value of the gradient at the point (1,-2). To do this, first obtain the indices of the point you want to work with. Then, use the indices to extract the corresponding gradient values from fx and fy.

x0 = 1;
y0 = -2;
t = (x == x0) & (y == y0);
indt = find(t);
f_grad = [fx(indt) fy(indt)]

f_grad = 1×2

  -16.0000   12.0400

The exact value of the gradient of $$f(x,y)=x^2{y}^3$$ at the point (1,-2) is

$$\begin{array}{cl}{(\nabla f)}_{(1,-2)}& =2x{y}^3\underset{}{\overset{ˆ}{i}}+3x^2{y}^2\underset{}{\overset{ˆ}{j}}\\ & =-16\underset{}{\overset{ˆ}{i}}+12\underset{}{\overset{ˆ}{j}}.\end{array}$$

Input Arguments

F — Input array

vector | matrix | multidimensional array

Input array, specified as a vector, matrix, or multidimensional array.

Data Types: single | double
Complex Number Support: Yes

h — Uniform spacing between points

1 (default) | scalar

Uniform spacing between points in all directions, specified as a scalar.

Example: [FX,FY] = gradient(F,2)

Data Types: single | double
Complex Number Support: Yes

hx, hy, hN — Spacing between points (as separate inputs)

1 (default) | scalars | vectors

Spacing between points in each direction, specified as separate inputs of scalars or vectors. The number of inputs must match the number of array dimensions of F. Each input can be a scalar or vector:

• A scalar specifies a constant spacing in that dimension.

• A vector specifies the coordinates of the values along the corresponding dimension of F. In this case, the length of the vector must match the size of the corresponding dimension.

Example: [FX,FY] = gradient(F,0.1,2)

Example: [FX,FY] = gradient(F,[0.1 0.3 0.5],2)

Example: [FX,FY] = gradient(F,[0.1 0.3 0.5],[2 3 5])

Data Types: single | double
Complex Number Support: Yes

Output Arguments

FX, FY, FZ, FN — Numerical gradients

arrays

Numerical gradients, returned as arrays of the same size as F. The first output FX is always the gradient along the 2nd dimension of F, going across columns. The second output FY is always the gradient along the 1st dimension of F, going across rows. For the third output FZ and the outputs that follow, the Nth output is the gradient along the Nth dimension of F.

More About

Numerical Gradient

The numerical gradient of a function is a way to estimate the values of the partial derivatives in each dimension using the known values of the function at certain points.

For a function of two variables, F(x,y), the gradient is

$$\nabla F=\frac{\partial F}{\partial x}\widehat{i}+\frac{\partial F}{\partial y}\widehat{j}.$$

The gradient can be thought of as a collection of vectors pointing in the direction of increasing values of F. In MATLAB^®, you can compute numerical gradients for functions with any number of variables. For a function of N variables, F(x,y,z, ...), the gradient is

$$\nabla F=\frac{\partial F}{\partial x}\widehat{i}+\frac{\partial F}{\partial y}\widehat{j}+\frac{\partial F}{\partial z}\widehat{k}+\mathrm{...}+\frac{\partial F}{\partial N}\widehat{n}.$$

Tips

• Use diff or a custom algorithm to compute multiple numerical derivatives, rather than calling gradient multiple times.

Algorithms

gradient calculates the central difference for interior data points. For example, consider a matrix with unit-spaced data, A, that has horizontal gradient G = gradient(A). The interior gradient values, G(:,j), are

G(:,j) = 0.5*(A(:,j+1) - A(:,j-1));

The subscript j varies between 2 and N-1, with N = size(A,2).

gradient calculates values along the edges of the matrix with single-sided differences:

G(:,1) = A(:,2) - A(:,1);
G(:,N) = A(:,N) - A(:,N-1);

If you specify the point spacing, then gradient scales the differences appropriately. If you specify two or more outputs, then the function also calculates differences along other dimensions in a similar manner. Unlike the diff function, gradient returns an array with the same number of elements as the input.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

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.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The gradient function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray (Parallel Computing Toolbox). For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced before R2006a