cf.Field.grad_xy

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

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.

See also

derivative, iscyclic, laplacian_xy, cf.curl_xy, cf.div_xy

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.

radius: optional

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 = f.grad_xy(radius='earth')
>>> fx, fy
(<CF Field: long_name=X gradient of specific_humidity(latitude(5), longitude(8)) m-1.rad-1>,
 <CF Field: long_name=Y gradient of specific_humidity(latitude(5), longitude(8)) m-1.rad-1>)
>>> 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]
 [-- -- -- -- -- -- -- --]]
>>> fx, fy = f.grad_xy(radius='earth', one_sided_at_boundary=True)
>>> 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.]]