easyclimate.core.diff

Geographic Finite Difference

Functions

calc_gradient(→ xarray.DataArray | xarray.Dataset)	Compute the gradient along the coordinate dim direction.
calc_dx_gradient(→ xarray.DataArray | xarray.Dataset)	Calculate the zonal gradient of the input data in physical units (meters).
calc_dlon_radian_gradient(...)	Calculate the gradient of the input data with respect to longitude in radians.
calc_dlon_degree_gradient(...)	Calculate the gradient of the input data with respect to longitude in degrees.
calc_dy_gradient(→ xarray.DataArray | xarray.Dataset)	Calculate the meridional gradient of the input data in physical units (meters).
calc_dlat_radian_gradient(...)	Calculate the gradient of the input data with respect to latitude in radians.
calc_dlat_degree_gradient(...)	Calculate the gradient of the input data with respect to latitude in degrees.
calc_dx_laplacian(→ xarray.DataArray | xarray.Dataset)	Calculation of the second-order partial derivative term (Laplace term) along longitude.
calc_dy_laplacian(→ xarray.DataArray | xarray.Dataset)	Calculation of the second-order partial derivative term (Laplace term) along latitude.
calc_dxdy_mixed_derivatives(...)	Calculation of second-order mixed partial derivative terms along longitude and latitude.
calc_p_gradient(→ xarray.DataArray)	Calculate the gradient along the barometric pressure direction in the p-coordinate system.
calc_time_gradient(→ xarray.DataArray)	Calculate the gradient along the time direction.
calc_dxdy_laplacian(→ xarray.DataArray)	Calculate the horizontal Laplace term.
calc_shear_stretch_deform(u_data, v_data[, lon_dim, ...])

Module Contents

easyclimate.core.diff.calc_gradient(data_input: xarray.DataArray | xarray.Dataset, dim: str, varargs: int = 1, edge_order: int = 2) → xarray.DataArray | xarray.Dataset

Compute the gradient along the coordinate dim direction.

The gradient is computed using second order accurate central differences in the interior points and either first or second order accurate one-sides (forward or backwards) differences at the boundaries. The returned gradient hence has the same shape as the input array.

Parameters

data_inputxarray.DataArray or xarray.Dataset.

The spatio-temporal data to be calculated.

dimstr.

Dimension(s) over which to apply gradient. By default gradient is applied over the time dimension.

varargs: list of scalar or array, optional

Spacing between f values. Default unitary spacing for all dimensions. Spacing can be specified using:

1. Single scalar to specify a sample distance for all dimensions.

2. N scalars to specify a constant sample distance for each dimension. i.e. \(\mathrm{d}x, \mathrm{d}y, \mathrm{d}z, ...\)

3. N arrays to specify the coordinates of the values along each dimension of F. The length of the array must match the size of the corresponding dimension.

4. Any combination of N scalars/arrays with the meaning of 2. and 3.

edge_order: {1, 2}, optional

Gradient is calculated using N-th order accurate differences at the boundaries. Default: 2.

Returns

The gradient along the coordinate dim direction (xarray.DataArray or xarray.Dataset).

See also

numpy.gradient

easyclimate.core.diff.calc_dx_gradient(data_input: xarray.DataArray | xarray.Dataset, lon_dim: str = 'lon', lat_dim: str = 'lat', min_dx: float = 1.0, edge_order: int = 2, R: float = 6371200.0) → xarray.DataArray | xarray.Dataset

Calculate the zonal gradient of the input data in physical units (meters).

This function computes the partial derivative \(\partial F / \partial x\), where \(x\) is the eastward distance along a parallel (in meters). It is the full physical zonal gradient on a sphere, given by:

\[\frac{\partial F}{\partial x} = \frac{1}{R \cos \varphi} \cdot \frac{\partial F}{\partial \lambda}\]

where \(R\) is the Earth’s radius, \(\varphi\) is latitude, and \(\lambda\) is longitude in radians. This is essential for dynamical calculations like advection or wave propagation in atmospheric/oceanic models.

The computation uses finite differences along the longitude dimension: \(\partial F / \partial x = (\partial F / \partial i) / (\partial x / \partial i)\), where \(i\) is the grid index. Longitude is assumed in degrees and converted to radians; latitude is broadcasted for the cosine factor.

Parameters

data_inputxarray.DataArray or xarray.Dataset

The spatio-temporal data to be calculated. If a Dataset, the gradient is applied to all data variables.

lon_dim: str, default: lon.

Longitude coordinate dimension name. By default, the gradient is applied over the lon dimension.

lat_dim: str, default: lat.

Latitude coordinate dimension name. Used to compute the cosine factor; broadcasted if necessary.

min_dx: float, default: 1.0 (\(\mathrm{m}\)).

The minimum acceptable value of dx (zonal spacing in meters), below which the output is set to NaN to avoid numerical instabilities from very small grid spacings. Set to a negative value to disable this check.

edge_order: {1, 2}, optional

Order of the finite difference used at the boundaries. 1 uses first-order accurate one-sided differences; 2 uses second-order accurate one-sided differences. Default: 2.

R: float, default: 6370000 (\(\mathrm{m}\)).

Radius of the Earth in meters (approximate mean radius). Can be adjusted for specific models.

Returns

xarray.DataArray or xarray.Dataset

The zonal gradient \(\partial F / \partial x\), with the same shape and coordinates as the input. Units are those of the input data divided by meters (e.g., if F is in K, output is K/m). Invalid regions (dx < min_dx) are NaN.

See also

• calc_gradient

• calc_dlon_radian_gradient

• calc_dy_gradient

easyclimate.core.diff.calc_dlon_radian_gradient(data_input: xarray.DataArray | xarray.Dataset, lon_dim: str = 'lon', edge_order: int = 2) → xarray.DataArray | xarray.Dataset

Calculate the gradient of the input data with respect to longitude in radians.

This function computes the partial derivative \(\partial F / \partial \lambda\), where \(\lambda\) is the longitude in radians. It is useful for spherical coordinate calculations, such as in wave activity flux (WAF) formulations, where angular gradients must be in radians for consistency with trigonometric functions and the Earth’s radius.

The computation uses finite differences:

\[\frac{\partial F}{\partial \lambda} = \frac{\partial F}{\partial i } / \frac{\partial \lambda}{\partial i},\]

where \(i\) is the grid index along the longitude dimension. Longitude values are assumed to be in degrees initially and converted to radians for the denominator.

Parameters

data_inputxarray.DataArray or xarray.Dataset

The spatio-temporal data to be calculated. If a Dataset, the gradient is applied to all data variables.

lon_dim: str, default: lon.

Longitude coordinate dimension name. By default, the gradient is applied over the lon dimension.

edge_order: {1, 2}, optional

Order of the finite difference used at the boundaries. 1 uses first-order accurate one-sided differences; 2 uses second-order accurate one-sided differences. Default: 2.

Returns

xarray.DataArray or xarray.Dataset

The gradient \(\partial F / \partial \lambda\) (in radians), with the same shape and coordinates as the input. Units are inherited from the input data divided by radians (e.g., if F is in K, output is K/rad).

easyclimate.core.diff.calc_dlon_degree_gradient(data_input: xarray.DataArray | xarray.Dataset, lon_dim: str = 'lon', edge_order: int = 2) → xarray.DataArray | xarray.Dataset

Calculate the gradient of the input data with respect to longitude in degrees.

This function computes the partial derivative \(\partial F / \partial \lambda\), where \(\lambda\) is the longitude in degrees. It is suitable for general-purpose gradient calculations where degree units are preferred for interpretability.

The computation uses finite differences:

\[\frac{\partial F}{\partial \lambda} = \frac{\partial F}{\partial i} / \frac{\partial \lambda}{\partial i},\]

where \(i\) is the grid index along the longitude dimension. Longitude values remain in degrees for the denominator.

Parameters

data_inputxarray.DataArray or xarray.Dataset

The spatio-temporal data to be calculated. If a Dataset, the gradient is applied to all data variables.

lon_dim: str, default: lon.

Longitude coordinate dimension name. By default, the gradient is applied over the lon dimension.

edge_order: {1, 2}, optional

Order of the finite difference used at the boundaries. 1 uses first-order accurate one-sided differences; 2 uses second-order accurate one-sided differences. Default: 2.

Returns

xarray.DataArray or xarray.Dataset

The gradient \(\partial F / \partial \lambda\) (in degrees), with the same shape and coordinates as the input. Units are inherited from the input data divided by degrees (e.g., if F is in K, output is K/deg).

See also

• calc_gradient

• calc_dlon_radian_gradient

• calc_dlat_degree_gradient

easyclimate.core.diff.calc_dy_gradient(data_input: xarray.DataArray | xarray.Dataset, lat_dim: str = 'lat', min_dy: float = 1.0, edge_order: int = 2, R: float = 6371200.0) → xarray.DataArray | xarray.Dataset

Calculate the meridional gradient of the input data in physical units (meters).

This function computes the partial derivative \(\partial F / \partial y\), where \(y\) is the northward distance along a meridian (in meters). It is the full physical meridional gradient on a sphere, given by:

\[\frac{\partial F}{\partial y} = \frac{1}{R} \cdot \frac{\partial F}{\partial \varphi}\]

where \(R\) is the Earth’s radius and \(\varphi\) is latitude in radians. This is essential for dynamical calculations like advection or vorticity in models.

The computation uses finite differences along the latitude dimension: \(\partial F / \partial y = (\partial F / \partial j) / (\partial y / \partial j)\), where \(j\) is the grid index. Latitude is assumed in degrees and converted to radians.

Parameters

data_inputxarray.DataArray or xarray.Dataset

The spatio-temporal data to be calculated. If a Dataset, the gradient is applied to all data variables.

lat_dim: str, default: lat.

Latitude coordinate dimension name. By default, the gradient is applied over the lat dimension.

min_dy: float, default: 1.0.

The minimum acceptable value of dy (meridional spacing in meters), below which the output is set to NaN to avoid numerical instabilities from very small grid spacings. Set to a negative value to disable this check. Unit: meters.

edge_order: {1, 2}, optional

Order of the finite difference used at the boundaries. 1 uses first-order accurate one-sided differences; 2 uses second-order accurate one-sided differences. Default: 2.

R: float, default: 6370000.

Radius of the Earth in meters (approximate mean radius). Can be adjusted for specific models.

Returns

xarray.DataArray or xarray.Dataset

The meridional gradient \(\partial F / \partial y\), with the same shape and coordinates as the input. Units are those of the input data divided by meters (e.g., if F is in K, output is K/m). Invalid regions (dy < min_dy) are NaN.

See also

• calc_gradient

• calc_dlat_radian_gradient

• calc_dx_gradient

easyclimate.core.diff.calc_dlat_radian_gradient(data_input: xarray.DataArray | xarray.Dataset, lat_dim: str = 'lat', edge_order: int = 2) → xarray.DataArray | xarray.Dataset

Calculate the gradient of the input data with respect to latitude in radians.

This function computes the partial derivative \(\partial F / \partial \phi\), where \(\phi\) is the latitude in radians. It is useful for spherical coordinate calculations, such as in wave activity flux (WAF) formulations.

The computation uses finite differences:

\[\frac{\partial F}{\partial \phi} = \frac{\partial F}{\partial j} / \frac{\partial \phi}{\partial j},\]

where \(j\) is the grid index along the latitude dimension. Latitude values are assumed to be in degrees initially and converted to radians for the denominator.

Parameters

data_inputxarray.DataArray or xarray.Dataset

The spatio-temporal data to be calculated. If a Dataset, the gradient is applied to all data variables.

lat_dim: str, default: lat.

Latitude coordinate dimension name. By default, the gradient is applied over the lat dimension.

edge_order: {1, 2}, optional

Order of the finite difference used at the boundaries. 1 uses first-order accurate one-sided differences; 2 uses second-order accurate one-sided differences. Default: 2.

Returns

xarray.DataArray or xarray.Dataset

The gradient \(\partial F / \partial \phi\) (in radians), with the same shape and coordinates as the input. Units are inherited from the input data divided by radians (e.g., if F is in K, output is K/rad).

See also

• calc_gradient

• calc_dlat_degree_gradient

• calc_dlon_radian_gradient

easyclimate.core.diff.calc_dlat_degree_gradient(data_input: xarray.DataArray | xarray.Dataset, lat_dim: str = 'lat', edge_order: int = 2) → xarray.DataArray | xarray.Dataset

Calculate the gradient of the input data with respect to latitude in degrees.

This function computes the partial derivative \(\partial F / \partial \phi\), where \(\phi\) is the latitude in degrees. It is suitable for general-purpose gradient calculations where degree units are preferred.

The computation uses finite differences:

\[\frac{\partial F}{\partial \phi} = \frac{\partial F}{\partial j} / \frac{\partial \phi}{\partial j},\]

where \(j\) is the grid index along the latitude dimension. Latitude values remain in degrees for the denominator.

Parameters

data_inputxarray.DataArray or xarray.Dataset

The spatio-temporal data to be calculated. If a Dataset, the gradient is applied to all data variables.

lat_dim: str, default: lat.

Latitude coordinate dimension name. By default, the gradient is applied over the lat dimension.

edge_order: {1, 2}, optional

Order of the finite difference used at the boundaries. 1 uses first-order accurate one-sided differences; 2 uses second-order accurate one-sided differences. Default: 2.

Returns

xarray.DataArray or xarray.Dataset

The gradient \(\partial F / \partial \phi\) (in degrees), with the same shape and coordinates as the input. Units are inherited from the input data divided by degrees (e.g., if F is in K, output is K/deg).

See also

• calc_gradient

• calc_dlat_radian_gradient

• calc_dlon_degree_gradient

easyclimate.core.diff.calc_dx_laplacian(data_input: xarray.DataArray | xarray.Dataset, lon_dim: str = 'lon', lat_dim: str = 'lat', min_dx2: float = 1000000000.0, edge_order: int = 2, R: float = 6371200.0) → xarray.DataArray | xarray.Dataset

Calculation of the second-order partial derivative term (Laplace term) along longitude.

\[\frac{\partial^2 F}{\partial x^2} = \frac{1}{(R \cos\varphi)^2} \cdot \frac{\partial^2 F}{\partial \lambda^2}\]

Parameters

data_inputxarray.DataArray or xarray.Dataset

The spatio-temporal data to be calculated.

lon_dim: str, default: lon.

Longitude coordinate dimension name. By default extracting is applied over the lon dimension.

lat_dim: str, default: lat.

Latitude coordinate dimension name. By default extracting is applied over the lat dimension.

min_dx2: float, default: 1e9.

The minimum acceptable value of \((\mathrm{d}x)^2\), below which parts will set nan to avoid large computational errors. The unit is m. You can set it to a negative value in order to remove this benefit.

edge_order: {1, 2}, optional

Gradient is calculated using N-th order accurate differences at the boundaries. Default: 1.

R: float, default: 6370000.

Radius of the Earth.

Returns

The second-order partial derivative term (Laplace term) along longitude (xarray.DataArray or xarray.Dataset).

See also

calc_gradient

easyclimate.core.diff.calc_dy_laplacian(data_input: xarray.DataArray | xarray.Dataset, lat_dim: str = 'lat', min_dy2: float = 1.0, edge_order: int = 2, R: float = 6371200.0) → xarray.DataArray | xarray.Dataset

Calculation of the second-order partial derivative term (Laplace term) along latitude.

\[\frac{\partial^2 F}{\partial y^2} = \frac{1}{R^2} \cdot \frac{\partial^2 F}{\partial \varphi^2}\]

Parameters

data_inputxarray.DataArray or xarray.Dataset

The spatio-temporal data to be calculated.

lat_dim: str, default: lat.

Latitude coordinate dimension name. By default extracting is applied over the lat dimension.

min_dy2: float, default: 1.0.

The minimum acceptable value of \((\mathrm{d}y)^2\), below which parts will set nan to avoid large computational errors. The unit is m. You can set it to a negative value in order to remove this benefit.

edge_order: {1, 2}, optional

Gradient is calculated using N-th order accurate differences at the boundaries. Default: 1.

R: float, default: 6370000.

Radius of the Earth.

Returns

The second-order partial derivative term (Laplace term) along latitude (xarray.DataArray or xarray.Dataset).

See also

calc_gradient

easyclimate.core.diff.calc_dxdy_mixed_derivatives(data_input: xarray.DataArray | xarray.Dataset, lon_dim: str = 'lon', lat_dim: str = 'lat', min_dxdy: float = 10000000000.0, edge_order: int = 2, R: float = 6371200.0) → xarray.DataArray | xarray.Dataset

Calculation of second-order mixed partial derivative terms along longitude and latitude.

\[\frac{\partial^2 F}{\partial x \partial y} = \frac{1}{R^2 \cos\varphi} \cdot \frac{\partial^2 F}{\partial \lambda \partial \varphi}\]

Parameters

data_inputxarray.DataArray or xarray.Dataset

The spatio-temporal data to be calculated.

lon_dim: str, default: lon.

Longitude coordinate dimension name. By default extracting is applied over the lon dimension.

lat_dim: str, default: lat.

Latitude coordinate dimension name. By default extracting is applied over the lat dimension.

min_dxdy: float, default: 1e10.

The minimum acceptable value of \(\mathrm{d}x\mathrm{d}y\), below which parts will set nan to avoid large computational errors. The unit is m. You can set it to a negative value in order to remove this benefit.

edge_order: {1, 2}, optional

Gradient is calculated using N-th order accurate differences at the boundaries. Default: 1.

R: float, default: 6370000.

Radius of the Earth.

Returns

The second-order mixed partial derivative terms along longitude and latitude (xarray.DataArray or xarray.Dataset).

See also

calc_gradient

easyclimate.core.diff.calc_p_gradient(data_input: xarray.DataArray, vertical_dim: str, vertical_dim_units: Literal['hPa', 'Pa', 'mbar']) → xarray.DataArray

Calculate the gradient along the barometric pressure direction in the p-coordinate system.

\[\frac{\partial F}{\partial p}\]

Parameters

data_inputxarray.DataArray or xarray.Dataset

The spatio-temporal data to be calculated.

vertical_dim: str.

Vertical coordinate dimension name.

vertical_dim_units: str.

The unit corresponding to the vertical p-coordinate value. Optional values are hPa, Pa, mbar.

Returns

The gradient along the barometric pressure direction in the p-coordinate system (xarray.DataArray or xarray.Dataset).

See also

calc_gradient

easyclimate.core.diff.calc_time_gradient(data_input: xarray.DataArray, time_units: str, time_dim: str = 'time') → xarray.DataArray

Calculate the gradient along the time direction.

\[\frac{\partial F}{\partial t}\]

Parameters

data_inputxarray.DataArray or xarray.Dataset

The spatio-temporal data to be calculated.

time_units: str.

The unit corresponding to the time dimension value. Optional values are seconds, months, years and so on.

time_dim: str, default: time.

The time coordinate dimension name.

Returns

The gradient along the time direction (xarray.DataArray or xarray.Dataset).

Caution

The units for partial derivative of time are \(\mathrm{s^{-1}}\).

See also

calc_gradient

easyclimate.core.diff.calc_dxdy_laplacian(data_input: xarray.DataArray, lon_dim: str = 'lon', lat_dim: str = 'lat', R: float = 6371200.0, spherical_coord: bool = True) → xarray.DataArray

Calculate the horizontal Laplace term.

rectangular coordinates

\[\nabla^2 F = \frac{\partial^2 F}{\partial x^2} + \frac{\partial^2 F}{\partial y^2}\]

Spherical coordinates

\[\nabla^2 F = \frac{\partial^2 F}{\partial x^2} + \frac{\partial^2 F}{\partial y^2} - \frac{1}{R} \frac{\partial F}{\partial y} \tan \varphi\]

Parameters

data_input: xarray.DataArray.

The spatio-temporal data to be calculated.

lon_dim: str, default: lon.

Longitude coordinate dimension name. By default extracting is applied over the lon dimension.

lat_dim: str, default: lat.

Latitude coordinate dimension name. By default extracting is applied over the lat dimension.

R: float, default: 6370000.

Radius of the Earth.

spherical_coord: bool, default: True.

Whether or not to compute the horizontal Laplace term in spherical coordinates.

Returns

The horizontal Laplace term. (xarray.DataArray).

easyclimate.core.diff.calc_shear_stretch_deform(u_data: xarray.DataArray, v_data: xarray.DataArray, lon_dim: str = 'lon', lat_dim: str = 'lat', edge_order: {1, 2} = 2, R: float = 6371200.0)

• https://www.ncl.ucar.edu/Document/Functions/Contributed/shear_stretch_deform_cfd.shtml

• Spensberger, C., & Spengler, T. (2014). A New Look at Deformation as a Diagnostic for Large-Scale Flow. Journal of the Atmospheric Sciences, 71(11), 4221-4234. https://doi.org/10.1175/JAS-D-14-0108.1