Ctrl+K

clouddrift.kinematics.spin

Contents

clouddrift.kinematics.spin#

clouddrift.kinematics.spin(u: ndarray, v: ndarray, time: ndarray, difference_scheme: str | None = 'forward', time_axis: int | None = -1) → float | ndarray[source]#

Compute spin continuously from velocities and times.

Spin is traditionally (Sawford, 1999; Veneziani et al., 2005) defined as (<u’dv’ - v’du’>) / (2 dt EKE) where u’ and v’ are eddy-perturbations of the velocity field, EKE is eddy kinetic energy, dt is the time step, and du’ and dv’ are velocity component increments during dt, and < > denotes ensemble average.

To allow computing spin based on full velocity fields, this function does not do any demeaning of the velocity fields. If you need the spin based on velocity anomalies, ensure to demean the velocity fields before passing them to this function. This function also returns instantaneous spin values, so the rank of the result is not reduced relative to the input.

u, v, 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. u.shape[-1]), use the time_axis optional argument to specify along which the spin should be calculated. u, v, and time must either have the same shape, or time must be a 1-d array with the same length as u.shape[time_axis].

Difference scheme can be 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#

unp.ndarray

Zonal velocity

vnp.ndarray

Meridional velocity

timearray-like

Time

difference_schemestr, optional

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

time_axisint, optional

Axis along which the time varies (default is -1)

Returns#

sfloat or np.ndarray

Spin

Raises#

ValueError

If u and v do not have the same shape. If the time axis is outside of the valid range ([-1, N-1]). If lengths of u, v, and time along time_axis are not equal. If difference_scheme is not “forward”, “backward”, or “centered”.

Examples#

>>> from clouddrift.kinematics import spin
>>> import numpy as np
>>> u = np.array([1., 2., -1., 4.])
>>> v = np.array([1., 3., -2., 1.])
>>> time = np.array([0., 1., 2., 3.])
>>> spin(u, v, time)
array([ 0.5       , -0.07692308,  1.4       ,  0.41176471])

Use difference_scheme to specify an alternative finite difference scheme for the velocity differences:

>>> spin(u, v, time, difference_scheme="centered")
array([0.5       , 0.        , 0.6       , 0.41176471])
>>> spin(u, v, time, difference_scheme="backward")
array([ 0.5       ,  0.07692308, -0.2       ,  0.41176471])

References#

Contents