roll

roll(x: array, /, shift: int | Tuple[int, ...], *, axis: int | Tuple[int, ...] | None = None) → array

Rolls array elements along a specified axis.

Array elements that roll beyond the last position are re-introduced at the first position.

Array elements that roll beyond the first position are re-introduced at the last position.

Parameters:

  • x (array) – input array.

  • shift (Union[int, Tuple[int, ...]]) – number of places by which the elements are shifted. If shift is a tuple, then axis must be a tuple of the same size, and each of the given axes must be shifted by the corresponding element in shift. If shift is an int and axis a tuple, then the same shift must be used for all specified axes. If a shift is positive, then array elements must be shifted positively (toward larger indices) along the dimension of axis. If a shift is negative, then array elements must be shifted negatively (toward smaller indices) along the dimension of axis.

  • axis (Optional[Union[int, Tuple[int, ...]]]) – axis (or axes) along which elements to shift. A valid axis must be an integer on the interval [-N, N), where N is the number of axes in x. If an axis is specified as a negative integer, the function must determine the axis along which to perform the operation by counting backward from the last axis (where -1 refers to the last axis). If provided an invalid axis, the function must raise an exception. If axis is None, the array must be flattened, shifted, and then restored to its original shape. Default: None.

Returns:

out (array) – an output array. The returned array must have the same data type as x. The returned array must have the same elements as x, but which are shifted relative to x.