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)#
Calculate the advection of a scalar field by 1D, 2D, or 3D winds.
If
scalar
is axarray.DataArray
, onlyu
,v
, and/orw
are required to compute advection. The horizontal and vertical spacing (dx
,dy
, anddz
) and axis numbers (x_dim
,y_dim
, andz_dim
) are automatically inferred fromscalar
. But ifscalar
is apint.Quantity
, the horizontal and vertical spacingdx
,dy
, anddz
needs to be provided, and each array should have one item less than the size ofscalar
along the applicable axis. Additionally,x_dim
,y_dim
, andz_dim
are required ifscalar
does not have the default […, Z, Y, X] ordering.dx
,dy
,dz
,x_dim
,y_dim
, andz_dim
are keyword-only arguments.parallel_scale
andmeridional_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
orxarray.DataArray
) – The quantity (an N-dimensional array) to be advected.u (
pint.Quantity
orxarray.DataArray
or None) – The wind component in the x dimension. An N-dimensional array.v (
pint.Quantity
orxarray.DataArray
or None) – The wind component in the y dimension. An N-dimensional array.w (
pint.Quantity
orxarray.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 ifxarray.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 ifxarray.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 ifxarray.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
orxarray.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)