# Documentation

## Syntax

`FX = gradient(F)[FX,FY] = gradient(F)[FX,FY,FZ,...] = gradient(F)[...] = gradient(F,h)[...] = gradient(F,h1,h2,...)`

## 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); [px,py] = gradient(z,.2,.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`.

collapse all

### 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));`

where `j` varies between `2` and `N-1`, where `N` is `size(A,2)`.

The gradient values along the edges of the matrix are calculated with single-sided differences, so that

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

If the point spacing is specified, then the differences are scaled appropriately. If two or more outputs are specified, `gradient` 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.