Field.grad_xy(x_wrap=None, one_sided_at_boundary=False, radius=None)[source]

Calculate the (X, Y) gradient vector.

The horizontal gradient vector of a scalar function is calculated from a field that has dimension coordinates of X and Y, in either Cartesian (e.g. plane projection) or spherical polar coordinate systems.

The horizontal gradient vector in Cartesian coordinates is given by:

$\nabla f(x, y) = \left( \frac{\partial f}{\partial x}, \frac{\partial f}{\partial y} \right)$

The horizontal gradient vector in spherical polar coordinates is given by:

$\nabla f(\theta, \phi) = \left( \frac{1}{r} \frac{\partial f}{\partial \theta}, \frac{1}{r \sin\theta} \frac{\partial f}{\partial \phi} \right)$

where r is radial distance to the origin, $$\theta$$ is the polar angle with respect to polar axis, and $$\phi$$ is the azimuthal angle.

The gradient vector components are calculated using centred finite differences apart from at the boundaries (see the x_wrap and one_sided_at_boundary parameters). If missing values are present then missing values will be returned at all points where a centred finite difference could not be calculated.

New in version 3.12.0.

Parameters
x_wrap: bool, optional

Whether the X axis is cyclic or not. By default x_wrap is set to the result of this call to the field construct’s iscyclic method: f.iscyclic('X'). If the X axis is cyclic then centred differences at one boundary will always use values from the other boundary, regardless of the setting of one_sided_at_boundary.

The cyclicity of the Y axis is always set to the result of f.iscyclic('Y').

one_sided_at_boundary: bool, optional

If True then one-sided finite differences are calculated at the non-cyclic boundaries. By default missing values are set at non-cyclic boundaries.

Specify the radius of the latitude-longitude plane defined in spherical polar coordinates. The radius is that which would be returned by this call of the field construct’s radius method: f.radius(default=radius). The radius is defined by the datum of a coordinate reference construct, and if and only if no such radius is found then the default value given by the radius parameter is used instead. A value of 'earth' is equivalent to a default value of 6371229 metres.

Returns
FieldList

The horizontal gradient vector of the scalar field.

Examples

>>> f = cf.example_field(0)
>>> print(f)
Field: specific_humidity (ncvar%q)
----------------------------------
Data            : specific_humidity(latitude(5), longitude(8)) 1
Cell methods    : area: mean
Dimension coords: latitude(5) = [-75.0, ..., 75.0] degrees_north
: longitude(8) = [22.5, ..., 337.5] degrees_east
: time(1) = [2019-01-01 00:00:00]
>>> f[...] = 0.1
>>> print(f.array)
[[0.1 0.1 0.1 0.1 0.1 0.1 0.1 0.1]
[0.1 0.1 0.1 0.1 0.1 0.1 0.1 0.1]
[0.1 0.1 0.1 0.1 0.1 0.1 0.1 0.1]
[0.1 0.1 0.1 0.1 0.1 0.1 0.1 0.1]
[0.1 0.1 0.1 0.1 0.1 0.1 0.1 0.1]]
>>> fx, fy
>>> print(fx.array)
[[0. 0. 0. 0. 0. 0. 0. 0.]
[0. 0. 0. 0. 0. 0. 0. 0.]
[0. 0. 0. 0. 0. 0. 0. 0.]
[0. 0. 0. 0. 0. 0. 0. 0.]
[0. 0. 0. 0. 0. 0. 0. 0.]]
>>> print(fy.array)
[[-- -- -- -- -- -- -- --]
[0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0]
[0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0]
[0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0]
[-- -- -- -- -- -- -- --]]