Return the gradient of an N-dimensional array.
The gradient is computed using second order accurate central differencesin 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.
Parameters: f : array_like
An N-dimensional array containing samples of a scalar function.
varargs : list of scalar or array, optional
Spacing between f values. Default unitary spacing for all dimensions.Spacing can be specified using:
single scalar to specify a sample distance for all dimensions.N scalars to specify a constant sample distance for each dimension.i.e. dx, dy, dz, ...N arrays to specify the coordinates of the values along eachdimension of F. The length of the array must match the size ofthe corresponding dimensionAny 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.
edge_order : {1, 2}, optional
Gradient is calculated using N-th order accurate differencesat the boundaries. Default: 1.
New in version 1.9.1.
axis : None or int or tuple of ints, optional
Gradient is calculated only along the given axis or axesThe default (axis = None) is to calculate the gradient for all the axesof the input array. axis may be negative, in which case it counts fromthe last to the first axis.
New in version 1.11.0.
Returns: gradient : ndarray or list of ndarray
A set of ndarrays (or a single 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.
Notes
Assuming that (i.e., has at least 3 continuousderivatives) and let be a non homogeneous stepsize, thespacing the finite difference coefficients are computed by minimisingthe consistency error :
By substituting and with their Taylor series expansion, this translates into solvingthe following the linear system:
The resulting approximation of is the following:
It is worth noting that if (i.e., data are evenly spaced)we find the standard second order approximation:
With a similar procedure the forward/backward approximations used forboundaries can be derived.
References
[R21]Quarteroni A., Sacco R., Saleri F. (2007) Numerical Mathematics(Texts in Applied Mathematics). New York: Springer.
[R22]Durran D. R. (1999) Numerical Methods for Wave Equationsin Geophysical Fluid Dynamics. New York: Springer.
[R23]Fornberg B. (1988) Generation of Finite Difference Formulas onArbitrarily Spaced Grids,Mathematics of Computation 51, no. 184 : 699-706.PDF.
Examples
>>> f = np.array([1, 2, 4, 7, 11, 16], dtype=np.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 coordinatesof 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=np.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 byaxis. In this example the first array stands for the gradient inrows and the second one in columns direction:
>>> np.gradient(np.array([[1, 2, 6], [3, 4, 5]], dtype=np.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 = [1., 1.5, 3.5]
>>> np.gradient(np.array([[1, 2, 6], [3, 4, 5]], dtype=np.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 thegradient is calculated
>>> np.gradient(np.array([[1, 2, 6], [3, 4, 5]], dtype=np.float), axis=0)
array([[ 2., 2., -1.],
[ 2., 2., -1.]])