repeat

repeat(x: array, repeats: int | array, /, *, axis: int | None = None) → array

Repeats each element of an array a specified number of times on a per-element basis.

Data-dependent output shape

When repeats is an array, the shape of the output array for this function depends on the data values in the repeats array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) can find this function difficult to implement without knowing the values in repeats. Accordingly, such libraries may choose to omit support for repeats arrays; however, conforming implementations must support providing a literal int. See Data-dependent output shapes section for more details.

Parameters:

  • x (array) – input array containing elements to repeat.

  • repeats (Union[int, array]) –

    the number of repetitions for each element.

    If axis is None, let M = prod(x.shape) and

    • if repeats is an array, repeats must be broadcast compatible with the shape (M,) (i.e., be a one-dimensional array having shape (1,) or (M,)).

    • if repeats is an integer, repeats must be broadcasted to the shape (M,).

    If axis is not None, let S = x.shape[axis] and

    • if repeats is an array, repeats must be broadcast compatible with the shape (S,) (i.e., be a one-dimensional array having shape (1,) or (S,)).

    • if repeats is an integer, repeats must be broadcasted to the shape (S,).

    If repeats is an array, the array must have an integer data type.

  • axis (Optional[int]) – the axis along which to repeat elements. 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 function must flatten the input array x and then repeat elements of the flattened input array and return the result as a one-dimensional output array. A flattened input array must be flattened in row-major, C-style order. Default: None.

Returns:

out (array) – an output array containing repeated elements. The returned array must have the same data type as x. If axis is None, the returned array must be a one-dimensional array; otherwise, the returned array must have the same shape as x, except for the axis along which elements were repeated.

Notes

  • For specification-conforming array libraries supporting hardware acceleration, providing an array for repeats can cause device synchronization due to an unknown output shape. For those array libraries where synchronization concerns are applicable, conforming array libraries should include a warning in their documentation regarding potential performance degradation when repeats is an array.

New in version 2023.12.