cf.div_xy

cf.div_xy(fx, fy, x_wrap=None, one_sided_at_boundary=False, radius=None)

Calculate the horizontal divergence of an (X, Y) vector.

The horizontal divergence is calculated from orthogonal vector component fields which have dimension coordinates of X and Y, in either Cartesian (e.g. plane projection) or spherical polar coordinate systems.

The horizontal divergence of the \((f_x, f_y)\) vector in Cartesian coordinates is given by:

\[\nabla \cdot (f_{x}(x,y), f_{y}(x,y)) = \frac{\partial f_x}{\partial x} + \frac{\partial f_y}{\partial y}\]

The horizontal divergence of the \((f_\theta, f_\phi)\) vector in spherical polar coordinates is given by:

\[\nabla \cdot (f_\theta(\theta,\phi), f_\phi(\theta,\phi)) = \frac{1}{r \sin\theta} \left( \frac{\partial (f_\theta \sin\theta)}{\partial \theta} + \frac{\partial f_\phi}{\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 divergence is 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

cf.curl_xy, cf.Field.derivative, cf.Field.grad_xy, cf.Field.iscyclic, cf.Field.laplacian_xy

Parameters

fx, fy: Field

The fields containing the X and Y vector components.

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 fx field construct’s iscyclic method:fx.iscyclic('X'). If the X axis is cyclic then centred differences at one X boundary will always use values from the other, regardless of the setting of one_sided_at_boundary.

The cyclicity of the Y axis is always set to the result of fy.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 fx field construct’s cf.Field.radius method: fx.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

Field

The horizontal curl of the (X, Y) fields.

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