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)[source]

Calculate the advection of a scalar field by the wind.

Parameters
• scalar (pint.Quantity or xarray.DataArray) – Array (with N-dimensions) with the quantity to be advected. Use xarray.DataArray to have dimension ordering automatically determined, otherwise, use default […, Z, Y, X] ordering or specify *_dim keyword arguments.

• u (pint.Quantity or xarray.DataArray or None) – N-dimensional arrays with units of velocity representing the flow, with a component of the wind in each dimension. For 1D advection, use 1 positional argument (with dx for grid spacing and x_dim to specify axis if not the default of -1) or use 1 applicable keyword argument (u, v, or w) for proper physical dimension (with corresponding d* for grid spacing and *_dim to specify axis). For 2D/horizontal advection, use 2 positional arguments in order for u and v winds respectively (with dx and dy for grid spacings and x_dim and y_dim keyword arguments to specify axes), or specify u and v as keyword arguments (grid spacings and axes likewise). For 3D advection, likewise use 3 positional arguments in order for u, v, and w winds respectively or specify u, v, and w as keyword arguments (either way, with dx, dy, dz for grid spacings and x_dim, y_dim, and vertical_dim for axes).

• v (pint.Quantity or xarray.DataArray or None) – N-dimensional arrays with units of velocity representing the flow, with a component of the wind in each dimension. For 1D advection, use 1 positional argument (with dx for grid spacing and x_dim to specify axis if not the default of -1) or use 1 applicable keyword argument (u, v, or w) for proper physical dimension (with corresponding d* for grid spacing and *_dim to specify axis). For 2D/horizontal advection, use 2 positional arguments in order for u and v winds respectively (with dx and dy for grid spacings and x_dim and y_dim keyword arguments to specify axes), or specify u and v as keyword arguments (grid spacings and axes likewise). For 3D advection, likewise use 3 positional arguments in order for u, v, and w winds respectively or specify u, v, and w as keyword arguments (either way, with dx, dy, dz for grid spacings and x_dim, y_dim, and vertical_dim for axes).

• w (pint.Quantity or xarray.DataArray or None) – N-dimensional arrays with units of velocity representing the flow, with a component of the wind in each dimension. For 1D advection, use 1 positional argument (with dx for grid spacing and x_dim to specify axis if not the default of -1) or use 1 applicable keyword argument (u, v, or w) for proper physical dimension (with corresponding d* for grid spacing and *_dim to specify axis). For 2D/horizontal advection, use 2 positional arguments in order for u and v winds respectively (with dx and dy for grid spacings and x_dim and y_dim keyword arguments to specify axes), or specify u and v as keyword arguments (grid spacings and axes likewise). For 3D advection, likewise use 3 positional arguments in order for u, v, and w winds respectively or specify u, v, and w as keyword arguments (either way, with dx, dy, dz for grid spacings and x_dim, y_dim, and vertical_dim for axes).

• dx (pint.Quantity or None, optional) – Grid spacing in applicable dimension(s). If using arrays, each array should have one item less than the size of scalar along the applicable axis. If scalar is an xarray.DataArray, these are automatically determined from its coordinates, and are therefore optional. Required if scalar is a pint.Quantity. These are keyword-only arguments.

• dy (pint.Quantity or None, optional) – Grid spacing in applicable dimension(s). If using arrays, each array should have one item less than the size of scalar along the applicable axis. If scalar is an xarray.DataArray, these are automatically determined from its coordinates, and are therefore optional. Required if scalar is a pint.Quantity. These are keyword-only arguments.

• dz (pint.Quantity or None, optional) – Grid spacing in applicable dimension(s). If using arrays, each array should have one item less than the size of scalar along the applicable axis. If scalar is an xarray.DataArray, these are automatically determined from its coordinates, and are therefore optional. Required if scalar is a pint.Quantity. These are keyword-only arguments.

• x_dim (int or None, optional) – Axis number in applicable dimension(s). Defaults to -1, -2, and -3 respectively for (…, Z, Y, X) dimension ordering. If scalar is an xarray.DataArray, these are automatically determined from its coordinates. These are keyword-only arguments.

• y_dim (int or None, optional) – Axis number in applicable dimension(s). Defaults to -1, -2, and -3 respectively for (…, Z, Y, X) dimension ordering. If scalar is an xarray.DataArray, these are automatically determined from its coordinates. These are keyword-only arguments.

• vertical_dim (int or None, optional) – Axis number in applicable dimension(s). Defaults to -1, -2, and -3 respectively for (…, Z, Y, X) dimension ordering. If scalar is an xarray.DataArray, these are automatically determined from its coordinates. These are keyword-only arguments.

Returns

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

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