clouddrift.kinematics.velocity_from_position

clouddrift.kinematics.velocity_from_position(x: ndarray, y: ndarray, time: ndarray, coord_system: str | None = 'spherical', difference_scheme: str | None = 'forward', time_axis: int | None = -1) → tuple[DataArray, DataArray]

Compute velocity from arrays of positions and time.

x and y can be provided as longitude and latitude in degrees if coord_system == “spherical” (default), or as easting and northing if coord_system == “cartesian”.

The units of the result are meters per unit of time if coord_system == “spherical”. For example, if the time is provided in the units of seconds, the resulting velocity is in the units of meters per second. Otherwise, if coord_system == “cartesian”, the units of the resulting velocity correspond to the units of the input. For example, if zonal and meridional displacements are in the units of kilometers and time is in the units of hours, the resulting velocity is in the units of kilometers per hour.

x, y, and time can be multi-dimensional arrays. If the time axis, along which the finite differencing is performed, is not the last one (i.e. x.shape[-1]), use the time_axis optional argument to specify along which axis should the differencing be done. x, y, and time must have the same shape.

Difference scheme can take one of three values:

1. “forward” (default): finite difference is evaluated as dx[i] = dx[i+1] - dx[i];

2. “backward”: finite difference is evaluated as dx[i] = dx[i] - dx[i-1];

3. “centered”: finite difference is evaluated as dx[i] = (dx[i+1] - dx[i-1]) / 2.

Forward and backward schemes are effectively the same except that the position at which the velocity is evaluated is shifted one element down in the backward scheme relative to the forward scheme. In the case of a forward or backward difference scheme, the last or first element of the velocity, respectively, is extrapolated from its neighboring point. In the case of a centered difference scheme, the start and end boundary points are evaluated using the forward and backward difference scheme, respectively.

Parameters

xarray_like

An N-d array of x-positions (longitude in degrees or zonal displacement in any unit)

yarray_like

An N-d array of y-positions (latitude in degrees or meridional displacement in any unit)

timearray_like

An N-d array of times as floating point values (in any unit)

coord_systemstr, optional

Coordinate system that x and y arrays are in; possible values are “spherical” (default) or “cartesian”.

difference_schemestr, optional

Difference scheme to use; possible values are “forward”, “backward”, and “centered”.

time_axisint, optional

Axis along which to differentiate (default is -1)

Returns

unp.ndarray

Zonal velocity

vnp.ndarray

Meridional velocity

Raises

ValueError

If x and y do not have the same shape. If time_axis is outside of the valid range. If lengths of x, y, and time along time_axis are not equal. If coord_system is not “spherical” or “cartesian”. If difference_scheme is not “forward”, “backward”, or “centered”.

Examples

Simple integration on a sphere, using the forward scheme by default:

>>> import numpy as np
>>> from clouddrift.kinematics import velocity_from_position
>>> lon = np.array([0., 1., 3., 6.])
>>> lat = np.array([0., 1., 2., 3.])
>>> time = np.array([0., 1., 2., 3.]) * 1e5
>>> u, v = velocity_from_position(lon, lat, time)
>>> u
array([1.11307541, 2.22513331, 3.33515501, 3.33515501])
>>> v
array([1.11324496, 1.11409224, 1.1167442 , 1.1167442 ])

Integration on a Cartesian plane, using the forward scheme by default:

>>> x = np.array([0., 1., 3., 6.])
>>> y = np.array([0., 1., 2., 3.])
>>> time = np.array([0., 1., 2., 3.])
>>> u, v = velocity_from_position(x, y, time, coord_system="cartesian")
>>> u
array([1., 2., 3., 3.])
>>> v
array([1., 1., 1., 1.])

See Also

position_from_velocity()