advection#

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:

  • scalar (pint.Quantity or xarray.DataArray) – The quantity (an N-dimensional array) to be advected.

  • u (pint.Quantity or xarray.DataArray or None) – The wind component in the x dimension. An N-dimensional array.

  • v (pint.Quantity or xarray.DataArray or None) – The wind component in the y dimension. An N-dimensional array.

  • w (pint.Quantity or xarray.DataArray or None) – The wind component in the z dimension. An N-dimensional array.

  • dx (pint.Quantity or None, optional) – Grid spacing in the x dimension.

  • dy (pint.Quantity or None, optional) – Grid spacing in the y dimension.

  • dz (pint.Quantity or None, optional) – Grid spacing in the z dimension.

  • x_dim (int or None, optional) – Axis number in the x dimension. Defaults to -1 for (…, Z, Y, X) dimension ordering.

  • y_dim (int or None, optional) – Axis number in the y dimension. Defaults to -2 for (…, Z, Y, X) dimension ordering.

  • vertical_dim (int or None, optional) – Axis number in the z dimension. Defaults to -3 for (…, Z, Y, X) dimension ordering.

  • parallel_scale (pint.Quantity, optional) – Parallel scale of map projection at data coordinate.

  • meridional_scale (pint.Quantity, optional) – Meridional scale of map projection at data coordinate.

  • latitude (pint.Quantity, optional) – Latitude of data. Optional if xarray.DataArray with latitude/longitude coordinates used as input. Also optional if parallel_scale and meridional_scale are given. If otherwise omitted, calculation will be carried out on a Cartesian, rather than geospatial, grid. Keyword-only argument.

  • longitude (pint.Quantity, optional) – Longitude of data. Optional if xarray.DataArray with latitude/longitude coordinates used as input. Also optional if parallel_scale and meridional_scale are given. If otherwise omitted, calculation will be carried out on a Cartesian, rather than geospatial, grid. Keyword-only argument.

  • crs (pyproj.crs.CRS, optional) – Coordinate Reference System of data. Optional if xarray.DataArray with MetPy CRS used as input. Also optional if parallel_scale and meridional_scale are given. If otherwise omitted, calculation will be carried out on a Cartesian, rather than geospatial, grid. Keyword-only argument.

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)

Examples using metpy.calc.advection#

Advection

Advection

Q-Vector

Q-Vector