dpnp.gradient

dpnp.gradient(f, *varargs, axis=None, edge_order=1)[source]

Return the gradient of an N-dimensional array.

The gradient is computed using second order accurate central differences in the interior points and either first or second order accurate one-sides (forward or backwards) differences at the boundaries. The returned gradient hence has the same shape as the input array.

For full documentation refer to numpy.gradient.

Parameters:

f ({dpnp.ndarray, usm_ndarray}) -- An N-dimensional array containing samples of a scalar function.
varargs ({scalar, list of scalars, list of arrays}, optional) --
Spacing between f values. Default unitary spacing for all dimensions. Spacing can be specified using:
1. Single scalar to specify a sample distance for all dimensions.
2. N scalars to specify a constant sample distance for each dimension. i.e. dx, dy, dz, ...
3. N arrays to specify the coordinates of the values along each dimension of f. The length of the array must match the size of the corresponding dimension
4. Any combination of N scalars/arrays with the meaning of 2. and 3.
If axis is given, the number of varargs must equal the number of axes. Default: 1.
axis ({None, int, tuple of ints}, optional) -- Gradient is calculated only along the given axis or axes. The default is to calculate the gradient for all the axes of the input array. axis may be negative, in which case it counts from the last to the first axis. Default: None.
edge_order ({1, 2}, optional) -- Gradient is calculated using N-th order accurate differences at the boundaries. Default: 1.

Returns:

gradient -- A list of dpnp.ndarray (or a single dpnp.ndarray if there is only one dimension) corresponding to the derivatives of f with respect to each dimension. Each derivative has the same shape as f.

Return type:

{dpnp.ndarray, list of ndarray}

See also

dpnp.diff: Calculate the n-th discrete difference along the given axis.
dpnp.ediff1d: Calculate the differences between consecutive elements of an array.

Examples

>>> import dpnp as np
>>> f = np.array([1, 2, 4, 7, 11, 16], dtype=float)
>>> np.gradient(f)
array([1. , 1.5, 2.5, 3.5, 4.5, 5. ])
>>> np.gradient(f, 2)
array([0.5 , 0.75, 1.25, 1.75, 2.25, 2.5 ])

Spacing can be also specified with an array that represents the coordinates of the values f along the dimensions. For instance a uniform spacing:

>>> x = np.arange(f.size)
>>> np.gradient(f, x)
array([1. , 1.5, 2.5, 3.5, 4.5, 5. ])

Or a non uniform one:

>>> x = np.array([0., 1., 1.5, 3.5, 4., 6.], dtype=float)
>>> np.gradient(f, x)
array([1. , 3. , 3.5, 6.7, 6.9, 2.5])

For two dimensional arrays, the return will be two arrays ordered by axis. In this example the first array stands for the gradient in rows and the second one in columns direction:

>>> np.gradient(np.array([[1, 2, 6], [3, 4, 5]], dtype=float))
(array([[ 2.,  2., -1.],
        [ 2.,  2., -1.]]),
 array([[1. , 2.5, 4. ],
        [1. , 1. , 1. ]]))

In this example the spacing is also specified: uniform for axis=0 and non uniform for axis=1

>>> dx = 2.
>>> y = np.array([1., 1.5, 3.5])
>>> np.gradient(np.array([[1, 2, 6], [3, 4, 5]], dtype=float), dx, y)
(array([[ 1. ,  1. , -0.5],
        [ 1. ,  1. , -0.5]]),
 array([[2. , 2. , 2. ],
        [2. , 1.7, 0.5]]))

It is possible to specify how boundaries are treated using edge_order

>>> x = np.array([0, 1, 2, 3, 4])
>>> f = x**2
>>> np.gradient(f, edge_order=1)
array([1., 2., 4., 6., 7.])
>>> np.gradient(f, edge_order=2)
array([0., 2., 4., 6., 8.])

The axis keyword can be used to specify a subset of axes of which the gradient is calculated

>>> np.gradient(np.array([[1, 2, 6], [3, 4, 5]], dtype=float), axis=0)
array([[ 2.,  2., -1.],
       [ 2.,  2., -1.]])