Accelerating the pace of engineering and science

# Documentation

## Definitions

The gradient of a function of two variables, F(x,y), is defined as

$\nabla F=\frac{\partial F}{\partial x}\stackrel{^}{i}+\frac{\partial F}{\partial y}\stackrel{^}{j}$

and can be thought of as a collection of vectors pointing in the direction of increasing values of F. In MATLAB® software, numerical gradients (differences) can be computed for functions with any number of variables. For a function of N variables, F(x,y,z, ...),

$\nabla F=\frac{\partial F}{\partial x}\stackrel{^}{i}+\frac{\partial F}{\partial y}\stackrel{^}{j}+\frac{\partial F}{\partial z}\stackrel{^}{k}+...$

## Description

FX = gradient(F), where F is a vector, returns the one-dimensional numerical gradient of F. Here FX corresponds to ∂F/∂x, the differences in x (horizontal) direction.

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

[FX,FY,FZ,...] = gradient(F), where F has N dimensions, returns the N components of the gradient of F. There are two ways to control the spacing between values in F:

• A single spacing value, h, specifies the spacing between points in every direction.

• N spacing values (h1,h2,...) specifies the spacing for each dimension of F. Scalar spacing parameters specify a constant spacing for each dimension. Vector parameters specify the coordinates of the values along corresponding dimensions of F. In this case, the length of the vector must match the size of the corresponding dimension.

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

[...] = gradient(F,h), where h is a scalar, uses h as the spacing between points in each direction.

[...] = gradient(F,h1,h2,...) with N spacing parameters specifies the spacing for each dimension of F.

## Examples

### Contour Plot of Vector Field

Calculate the 2-D gradient of on a grid.

```v = -2:0.2:2;
[x,y] = meshgrid(v);
z = x .* exp(-x.^2 - y.^2);
```

Plot the contour lines and vectors in the same figure.

```contour(v,v,z)
hold on
quiver(v,v,px,py)
hold off
```

### Specify Dimensional Spacing of Points

Create a 3-D array.

```F(:,:,1) = magic(3);
F(:,:,2) = pascal(3);
```

The command,

`gradient(F)`

takes dx = dy = dz = 1. However, the command,

`[PX,PY,PZ] = gradient(F,0.2,0.1,0.2) `

takes dx = 0.2, dy = 0.1, and dz = 0.2.

expand all

### Algorithms

gradient calculates the central difference between data points. For an array, matrix, or vector with N values in each row, the ith value is defined by

${B}_{i}=\frac{1}{2}\sum _{i=2}^{N-1}\left({A}_{i+1}-{A}_{i-1}\right).$

The gradient at the end points, where i=1 and i=N, is calculated with a single-sided difference between the endpoint value and the next adjacent value within the row. If two or more outputs are specified, gradient also calculates central differences along other dimensions. Unlike the diff function, gradient returns an array with the same number of elements as the input.