metpy.calc.advection(scalar, u=None, v=None, w=None, *, dx=None, dy=None, dz=None, x_dim=-1, y_dim=-2, vertical_dim=-3, parallel_scale=None, meridional_scale=None, latitude=None, longitude=None, crs=None)[source]#

Calculate the advection of a scalar field by 1D, 2D, or 3D winds.

If scalar is a xarray.DataArray, only u, v, and/or w are required to compute advection. The horizontal and vertical spacing (dx, dy, and dz) and axis numbers (x_dim, y_dim, and z_dim) are automatically inferred from scalar. But if scalar is a pint.Quantity, the horizontal and vertical spacing dx, dy, and dz needs to be provided, and each array should have one item less than the size of scalar along the applicable axis. Additionally, x_dim, y_dim, and z_dim are required if scalar does not have the default […, Z, Y, X] ordering. dx, dy, dz, x_dim, y_dim, and z_dim are keyword-only arguments.

parallel_scale and meridional_scale specify the parallel and meridional scale of map projection at data coordinate, respectively. They are optional when (a) xarray.DataArray with latitude/longitude coordinates and MetPy CRS are used as input or (b) longitude, latitude, and crs are given. If otherwise omitted, calculation will be carried out on a Cartesian, rather than geospatial, grid. Both are keyword-only arguments.

Parameters:
Returns:

pint.Quantity or xarray.DataArray – An N-dimensional array containing the advection at all grid points.

Notes

This implements the advection of a scalar quantity by wind:

$-\mathbf{u} \cdot \nabla = -(u \frac{\partial}{\partial x} + v \frac{\partial}{\partial y} + w \frac{\partial}{\partial z})$

Changed in version 1.0: Changed signature from (scalar, wind, deltas)